http://docs.360works.com/api.php?action=feedcontributions&user=Sarah&feedformat=atom360Works Product Documentation Wiki - User contributions [en]2024-03-28T16:42:48ZUser contributionsMediaWiki 1.19.1http://docs.360works.com/index.php/MJMMJM2014-02-12T18:22:32Z<p>Sarah: Created MJM Page</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==MJM Innovations==<br />
<br />
MJM Innovations provides Taxicard payment processing, and is a supported gateway in Plastic 2. Please check the demo file included as a download with Plastic 2 for an example of its use. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the MJM Innovations gateway, and use your '''Source ID''' and the '''Trip ID''' as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of Merchant UUID and API Key. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
sourceId, <br />
tripId;<br />
...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("MJM")] <br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. <br />
<br />
Once you properly configure your merchant account, you can quickly and easily process payment transactions.<br />
<br />
You must provide the following information for a credit card payment transaction:<br />
*Source ID <br />
*Trip ID<br />
*Dollar amount<br />
*Credit card number<br />
*Driver ID<br />
*Vehicle ID<br />
*GPS<br />
<br />
<br />
Returns: the CCProcessPayment function will process a transaction and return a transaction ID. This function returns a transaction ID if the transaction is successful or the word ERROR if the transaction fails. For detailed information about the most recent transaction failure, call the CCLastError function before calling any other transaction-processing function.<br />
<br />
In your script, you would then have a second line after setting the gateway.<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessPayment(<br />
sourceId, <br />
tripId;<br />
dollarAmount;<br />
cardNumber;<br />
expDate; //Optional<br />
"driverId=";<br />
"vehicleId=";<br />
"gps=")<br />
</pre><br />
<br />
'''Note''': It is important to store the resulting transaction ID because you may need it later to void the transaction, issue a refund or capture a previously authorized transaction.<br />
<br />
You may submit optional parameters to most of Plastic's payment-transaction processing functions. These parameters will be submitted to the payment gateway along with the basic transaction information. Although they are not usually required to process an order, these parameters can be useful for tasks such as address verification or linking a transaction to a customer id or an invoice number. To supply additional parameters to a function call, add them to the end of the parameter list after the last required parameter, using a "key=value" syntax.<br />
<br />
<pre>Set Variable $result Value:<br />
CCProcessPayment(<br />
sourceId, <br />
tripId;<br />
dollarAmount;<br />
cardNumber;<br />
expDate; //Optional<br />
"driverId=";<br />
"vehicleId=";<br />
"gps=";<br />
"passengers=" & Payment::Passenger;<br />
"address=" & Payment::Address;<br />
"city=" & Payment::City;<br />
"state=" & Payment::State;<br />
"zip=" & Payment::Zip)</pre><br />
<br />
{{Template:Using Card Readers}}<br />
<br />
MJM Innovations will only accept track 2 data.<br />
<br />
Set Variable [$result; Value:<br />
CCProcessPayment(<br />
sourceId;<br />
tripId;<br />
dollarAmount;<br />
"";<br />
"";<br />
"track2=;1234123412341234=11121010000000000111?")]<br />
<br />
Both ways of submitting transactions will accept the following optional parameters:<br />
<br />
* Passengers<br />
* Address<br />
* City<br />
* State<br />
* Zip<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/BluePayBluePay2014-02-12T17:44:50Z<p>Sarah: Removed end dates from subscriptions</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==BluePay==<br />
<br />
BluePay can process a wide variety of transactions, and supports eCheck / ACH payments, profile-based payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the BluePay gateway, and use your '''Account ID''' and the '''Secret Key''' as the first two parameters for every plug-in function call that performs a transaction. You may also pass in the optional parameter user. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key''; this is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
accountId;<br />
secretKey; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. <br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("BluePay"]</pre><br />
<br />
'''Returns''': 1 if a valid gateway is provided, ERROR otherwise.<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date.<br />
<br />
{{Template:Processing Payments|accountId|secretKey}}<br />
<br />
BluePay also requires the card's verification code in combination with the standard requirements for the function. You can pass in this extra, required variable by adding, passed in as an additional parameter, using "verificationCode="<br />
<br />
{{Template:BluePay Optional Parameters}}<br />
<br />
=== Processing ACH Payments ===<br />
<br />
{{Template:Processing ACH payments|accountId|secretKey}}<br />
<br />
BluePay does not require a bank name, or account holder's first or last name. However, you must pass in the achType as another parameter.<br />
<br />
{{Template:BluePay Optional Parameters}}<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|accountId|secretKey}}<br />
<br />
Set Variable [$result Value: <br />
CCProcessAuthorizedPayment(<br />
accountId;<br />
secretKey;<br />
previousTransactionId;<br />
dollarAmount)]<br />
<br />
The dollarAmount is not required to process the authorized payment. CCProcessAuthorizedPayment accepts the same optional parameters as CCProcessPayment.<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
Set Variable [$result; Value:<br />
CCProcessPayment(<br />
accountId;<br />
secretKey;<br />
chargeAmount;<br />
"";<br />
"";<br />
"track1=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
<br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|accountId|secretKey}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|accountId|secretKey}}<br />
<br />
== Subscription Services ==<br />
<br />
With subscriptions, payments can automatically be debited to a credit card or a bank account on a time period you specify. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. <br />
<br />
Valid pay periods include DAY, MONTH, WEEK, and YEAR. Frequency indicates how often in that period. For example, a biweekly subscription would have a pay period of WEEK and a frequency of 2. Optional parameters are italicized. <br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCModifySubscription</big> ||<big>CCDeleteSubscription</big><br />
|-<br />
|accountId||secretKey||accountId<br />
|-<br />
|accountId||secretKey||secretKey<br />
|-<br />
|dollarAmount||previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|cardNumber||''dollarAmount''<br />
|-<br />
|expirationDate||''cardNumber''<br />
|-<br />
|"";||''expirationDate''<br />
|-<br />
|''numberOfInstallments''||"";<br />
|-<br />
|startDate||''numberOfInstallments''<br />
|-<br />
|payPeriod||startDate<br />
|-<br />
|frequency||payPeriod<br />
|-<br />
|"verificationCode=" || frequency<br />
|-<br />
| ||"verificationCode="<br />
|}<br />
<br />
{{Template:BluePay Optional Parameters}}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
== Payment Profiles ==<br />
<br />
Typically, you pass a payment profile ID to the gateway for a Payment Profile. With BluePay, there are no IDs. You can, however, pass in the previous transaction ID and use that to run another charge without having to rekey payment data.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
|-<br />
|accountId<br />
|-<br />
|secretKey<br />
|-<br />
|"";<br />
|-<br />
|paymentProfileId (previous transaction ID)<br />
|-<br />
|dollarAmount<br />
|-<br />
|"verificationCode="<br />
|}<br />
<br />
{{Template:BluePay Optional Parameters}}<br />
<br />
== Getting Response Information and Using Helper Functions ==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/BluePayBluePay2014-02-12T17:21:15Z<p>Sarah: Creation of Blue Pay page</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==BluePay==<br />
<br />
BluePay can process a wide variety of transactions, and supports eCheck / ACH payments, profile-based payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the BluePay gateway, and use your '''Account ID''' and the '''Secret Key''' as the first two parameters for every plug-in function call that performs a transaction. You may also pass in the optional parameter user. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key''; this is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
accountId;<br />
secretKey; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. <br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("BluePay"]</pre><br />
<br />
'''Returns''': 1 if a valid gateway is provided, ERROR otherwise.<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date.<br />
<br />
{{Template:Processing Payments|accountId|secretKey}}<br />
<br />
BluePay also requires the card's verification code in combination with the standard requirements for the function. You can pass in this extra, required variable by adding, passed in as an additional parameter, using "verificationCode="<br />
<br />
{{Template:BluePay Optional Parameters}}<br />
<br />
=== Processing ACH Payments ===<br />
<br />
{{Template:Processing ACH payments|accountId|secretKey}}<br />
<br />
BluePay does not require a bank name, or account holder's first or last name. However, you must pass in the achType as another parameter.<br />
<br />
{{Template:BluePay Optional Parameters}}<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|accountId|secretKey}}<br />
<br />
Set Variable [$result Value: <br />
CCProcessAuthorizedPayment(<br />
accountId;<br />
secretKey;<br />
previousTransactionId;<br />
dollarAmount)]<br />
<br />
The dollarAmount is not required to process the authorized payment. CCProcessAuthorizedPayment accepts the same optional parameters as CCProcessPayment.<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
Set Variable [$result; Value:<br />
CCProcessPayment(<br />
accountId;<br />
secretKey;<br />
chargeAmount;<br />
"";<br />
"";<br />
"track1=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
<br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|accountId|secretKey}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|accountId|secretKey}}<br />
<br />
== Subscription Services ==<br />
<br />
With subscriptions, payments can automatically be debited to a credit card or a bank account on a time period you specify. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. <br />
<br />
Valid pay periods include DAY, MONTH, WEEK, and YEAR. Frequency indicates how often in that period. For example, a biweekly subscription would have a pay period of WEEK and a frequency of 2. Optional parameters are italicized. <br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCModifySubscription</big> ||<big>CCDeleteSubscription</big><br />
|-<br />
|accountId||secretKey||accountId<br />
|-<br />
|accountId||secretKey||secretKey<br />
|-<br />
|dollarAmount||previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|cardNumber||''dollarAmount''<br />
|-<br />
|expirationDate||''cardNumber''<br />
|-<br />
|"";||''expirationDate''<br />
|-<br />
|''numberOfInstallments''||"";<br />
|-<br />
|startDate||''numberOfInstallments''<br />
|-<br />
|"";||startDate<br />
|-<br />
|payPeriod||"";<br />
|-<br />
|frequency||payPeriod<br />
|-<br />
|"verificationCode=" || frequency<br />
|-<br />
| ||"verificationCode="<br />
|}<br />
<br />
{{Template:BluePay Optional Parameters}}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
== Payment Profiles ==<br />
<br />
Typically, you pass a payment profile ID to the gateway for a Payment Profile. With BluePay, there are no IDs. You can, however, pass in the previous transaction ID and use that to run another charge without having to rekey payment data.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
|-<br />
|accountId<br />
|-<br />
|secretKey<br />
|-<br />
|"";<br />
|-<br />
|paymentProfileId (previous transaction ID)<br />
|-<br />
|dollarAmount<br />
|-<br />
|"verificationCode="<br />
|}<br />
<br />
{{Template:BluePay Optional Parameters}}<br />
<br />
== Getting Response Information and Using Helper Functions ==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/Template:BluePay_Optional_ParametersTemplate:BluePay Optional Parameters2014-02-12T16:54:07Z<p>Sarah: Added blue pay parameters</p>
<hr />
<div><center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|invoiceNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|orderId<br />
|an arbitrary order ID for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|companyName <br />
|the billing company name<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|}<br />
</center></div>Sarahhttp://docs.360works.com/index.php/Docubin_-_Quick_StartDocubin - Quick Start2014-02-11T21:50:32Z<p>Sarah: Updated to use FM12</p>
<hr />
<div>[[DocuBin]] - Quick Start<br />
<br />
==Minimum Requirements==<br />
* FileMaker Pro 12 or 13<br />
* DocuBin.fmp12<br />
* DocuBinUtility.fmp12<br />
* DocuBinWSM.fmp12<br />
* SuperContainer<br />
* (Plugins are installed via Autoupdate)<br />
<br />
==Getting started with DocuBin==<br />
<br />
# Download, install, and configure [http://www.360works.com/supercontainer SuperContainer]<br />
# Open DocuBin.fmp12 and select either 'Create Account' or 'External Authentication'. If you are using External Authentication create the following groups on your Open/Active Directory Server: docubinadmin, docubinuser.<br />
# Login with a DocuBin admin account and:<br />
## register DocuBin<br />
## set the SuperContainer Base URL<br />
# Insert some folders and start using DocuBin.<br />
<br />
==Updating DocuBin==<br />
<br />
# Place your old copies of DocuBin.fmp12 and DocuBinUtility.fmp12 into the subfolder 'Old', located inside your new DocuBin download folder.<br />
# Open the new copy of Docubin.<br />
# Select the option 'Import Files and Settings'.<br />
# Click 'Import'. If you are prompted for authentication, use the system account and password from the old copy of DocuBin.<br />
# When the update is complete you can re-login to the new copy of Docubin with the accounts and passwords you created in your old copy. Make sure to save your old copies somewhere safe.<br />
<br />
==Installing Plugins==<br />
<br />
In addition to SuperContainer, DocuBin requires several plugins to function. By default, DocuBin is configured to use 360Works' server to automatically install these plugins for you. If you prefer to host these plugins yourself:<br />
<br />
# Open fmp://autoupdate12.360works.com/AutoUpdate360Works and follow the directions to download and install the plugins to your FileMaker Server.<br />
# Open DocuBin.fmp12<br />
# Select the menu '''''Docubin Settings…''''', which can be found under the menu '''''FileMaker Pro (Advanced)''''' on Macs, or under the menu '''''Help''''' on Windows.<br />
# Select '''''General'''''. At the bottom where the section is titled '''''AutoUpdate''''', change the selection from '''''360Works''''' to '''''Local'''''.<br />
<br />
'''Plugin not loading?'''<br />
<br />
DocuBin uses FileMaker's auto update functionality to download FileMaker extensions to a user's FileMaker extension directory. If extensions are also installed in the FileMaker extension directory there will be a conflict and the plugin will not load or function correctly. Also, any custom ScriptMaster plugins created prior to version 4.123 would cause a plugin to load or function incorrectly.<br />
<br />
<br />
==Server-Side Scripts==<br />
<br />
If you are hosting DocuBin with FileMaker Server, add the scripts below to your FileMaker Server's list of scheduled scripts:<br />
<br />
* Run Every Day</div>Sarahhttp://docs.360works.com/index.php/DocuBin_Enterprise_EditionDocuBin Enterprise Edition2014-02-11T21:44:08Z<p>Sarah: Updated to use FM12</p>
<hr />
<div>[[DocuBin]] - Enterprise Edition<br />
<br />
==Minimum System Requirements==<br />
<br />
* You must be running FileMaker 12 Server, FileMaker 12 Server Advanced, or FileMaker Server 13<br />
* The FileMaker Web Publishing Engine must be enabled<br />
* PHP publishing must be enabled<br />
* XML publishing must be enabled<br />
* The FileMaker PHP API must be installed<br />
<br />
: ''https://fmhelp.filemaker.com/docs/13/en/fms13_getting_started.pdf''<br />
<br />
* The Web Client will work in any modern browser.<br />
* WebDAV has been tested on Mac OS X 10.6 and Windows 7. It may work on earlier versions as well.<br />
<br />
: '''IMPORTANT''' - If you are attempting to map a WebDAV share to a drive letter on Windows, WebDAV will not work by default unless WebDAV is used over SSL. '''360Works recommends that you configure you FileMaker Server to operate over SSL if you wish to map shares on Windows.''' However, if you choose not to configure your FileMaker Server to operate over SSL, you can follow the instructions at the following link to use WebDAV without SSL encryption: http://code.google.com/p/sabredav/wiki/Windows#Authentication<br />
<br />
<br />
==Installation==<br />
<br />
# Deploy DocuBin.fmp12, DocuBinUtility.fmp12, and DocuBinWSM.fmp12 to your FileMaker Server.<br />
# Copy the '''''websvcmgr_docubin.php''''' file into your Web Server document root. This is where you would normally put PHP files for use with Web Publishing. On Mac OS X 10.6 and earlier, this defaults to ''/Library/WebServer/Documents''. For Mac OS X 10.7 and later, this defaults to "/Library/Server/Web/Data/Sites/Default" . On Windows, this defaults to ''C:\Inetpub\wwwroot''. Users with FileMaker Server 13 will find it in ''FileMaker Server/HTTPServer/htdocs/'' for FileMaker 13<br />
# Stop the FileMaker Web Publishing engine. <br />
# Run the Enterprise Edition installer for your operating system on the machine running Web Publishing.<br />
# Restart the FileMaker Web Publishing engine.<br />
<br />
<br />
==Basic Setup==<br />
<br />
# Login to DocuBin with an admin account<br />
# Open DocuBin Settings...<br />
# Select Enterprise Edition<br />
# Set the 'Web Services URL' to point to the computer running the FileMaker Web Publishing Engine. For example, if your server's DNS name is ''fmserver.xyz.com'', you would enter ''http://fmserver.xyz.com''.<br />
<br />
<br />
==Advanced Setup==<br />
<br />
DocuBin Enterprise Edition assumes a default, single-machine deployment of FileMaker Server. The steps below should help with any other deployments.<br />
<br />
===Web Publishing Engine on a different port===<br />
<br />
By default, the FileMaker Server Web Publishing Engine is set to run on port 80. If you wish to use another port, follow these directions:<br />
<br />
# Login to DocuBin with an admin account<br />
# Open DocuBin Settings...<br />
# Select Enterprise Edition<br />
# Set the 'Web Services URL' to point to the computer running the FileMaker Web Publishing Engine. For example, if your server's DNS name is ''fmserver.xyz.com'' and the Web Publishing Engine is set to run on port 8080, you would enter ''http://fmserver.xyz.com:8080''.<br />
<br />
You will also need to make the following modification to the '''''websvcmgr_docubin.php''''' file:<br />
<br />
//Before<br />
define( 'HOST', '127.0.0.1' ); //Do not edit this without first consulting the support staff at 360Works<br />
<br />
//After<br />
define( 'HOST', '127.0.0.1:8080' ); //Do not edit this without first consulting the support staff at 360Works<br />
<br />
===Web Server on a different port or machine===<br />
<br />
If you are running a three-machine deployment, or if your web server is running on any port other that 80:<br />
<br />
Open the file:<br />
<br />
'''FileMaker Server 11'''<br />
/FileMaker Server/Web Publishing/publishing-engine/cwpe-tomcat/conf/Catalina/localhost/DocuBin.xml<br />
<br />
'''FileMaker Server 12'''<br />
/FileMaker Server/Web Publishing/publishing-engine/jwpc-tomcat/conf/Catalina/localhost/DocuBin.xml<br />
<br />
And modify the address 'localhost' to the address/port of your Web Server. Be careful because there may be a commented line, and modifying localhost on that line won't do anything:<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<Context path="/"><br />
<Parameter name="wsmAddress" value="http://localhost/websvcmgr_docubin.php"/><br />
<Parameter name="filesRoot" value=""/><br />
<Parameter name="authenticationRealm" value="DocuBin" /><br />
</Context><br />
<br />
==Demo mode and registration==<br />
<br />
If you have purchased or upgraded to an Enterprise Edition License, you should see 'Congratulations' in a white box on the Enterprise Edition layout. If not, Enterprise Edition will run for 2 hours in demo mode. Demo mode is fully functional, with no limitations. You can start a new 2 hour demo mode by clicking the 'Start Demo Mode' button.<br />
<br />
<br />
==Enterprise Edition==<br />
<br />
The url to access your DocuBin files through WebDAV or the Web Client is ''http://fmserver.xyz.com/DocuBin/webdav/''<br />
<br />
<br />
===WebDav===<br />
<br />
'''Mac OS X'''<br />
<br />
''http://docs.info.apple.com/article.html?path=Mac/10.6/en/8304.html''<br />
<br />
# In the Finder, choose Go > "Connect to Server," <br />
# Enter ''http://fmserver.xyz.com/DocuBin/webdav/'' into the address field and click Connect<br />
# Enter a DocuBin account name and password and click Connect<br />
<br />
<br />
'''Windows:''' <br />
<br />
''http://windows.microsoft.com/en-US/windows7/Create-a-shortcut-to-map-a-network-drive''<br />
<br />
# Open Computer by clicking the Start button, and then clicking Computer.<br />
# Click Map network drive.<br />
# In the Drive list, click a drive letter. You can choose any available letter.<br />
# In the Folder box, type ''http://fmserver.xyz.com/DocuBin/webdav/''. To connect every time you log on to your computer, select the Reconnect at logon check box.<br />
# Click Finish.<br />
# Enter a DocuBin account name and password<br />
<br />
<br />
===Web Client===<br />
<br />
DocuBin Enterprise Edition supports all modern web browsers. Pick your favorite and go to ''http://fmserver.xyz.com/DocuBin/files/''. Enter a DocuBin account name and password when prompted.<br />
<br />
<br />
==Troubleshooting==<br />
===Log files===<br />
<br />
If you contact 360Works for support, we may request a copy of your log files to help with troubleshooting problems.<br />
<br />
If you are on a Mac, switch to the Finder and select 'Go->Go To Folder...' from the menubar. Type in '/tmp' and hit the 'go' button. You should see a folder open up showing everything in your /tmp folder; the log file is called '''''websvcmgr.log'''''<br />
<br />
If you are on Mac OS X, the file will be at '''''/tmp/websvcmgr.log'''''<br />
If you are on Windows XP, the file will be at '''''C:\WINDOWS\TEMP\websvcmgr.log'''''<br />
<br />
===Connection Failed===<br />
If you get a 'Connection Failed' message, check the server name or IP address you entered, and then try again. Also, make sure the demo period for Enterprise Edition has not expired.<br />
<br />
===HTTP Status 500===<br />
<br />
If you get an 'HTTP Status 500' message while trying to access the Web Client, make sure that the demo period for Enterprise Edition has not expired.<br />
<br />
===Bad Request (Invalid Hostname) Error===<br />
<br />
If end users are receiving errors, one cause might be that your server is not configured to allow internal access via localhost. If you cannot or do not want to resolve this issue via the server, you can change a line in the 'websvcmgr_docubin.php' file. The following example assumes your server's DNS name is 'http://fmserver.xyz.com'.<br />
<br />
//Before<br />
define( 'HOST', '127.0.0.1' ); //Do not edit this without first consulting the support staff at 360Works<br />
<br />
//After<br />
define( 'HOST', 'fmserver.xyz.com' ); //Do not edit this without first consulting the support staff at 360Works</div>Sarahhttp://docs.360works.com/index.php/DocuBin_DeveloperDocuBin Developer2014-02-11T21:37:09Z<p>Sarah: Updated to use FM12</p>
<hr />
<div>[[DocuBin]] - Developer<br />
<br />
Since we plan to release fixes and updates to DocuBin, we wanted to have a way for developers to integrate DocuBin into their solutions without having to make any actual changes to DocuBin. We have extended DocuBin's feature set to help achieve this goal.<br />
<br />
==Unlocking DocuBin==<br />
<br />
# Open DocuBin with a DocuBin admin account.<br />
# Select the menu option "About DocuBin…", which can be found under the menu "FileMaker Pro (Advanced)" on Macs, and under the menu "Help" on Windows.<br />
# Select the option "Unlock." <br />
: • If this is the first time you are unlocking DocuBin, enter a password for the developer account, and click "Login". DocuBin will now be unlocked.<br />
: • If you have previous unlocked DocuBin (starting in version 1.0038) DocuBin will now be unlocked. Enter the developer password and click "Login"<br />
<br />
==Developer Scripts==<br />
<br />
The scripts below can be integrated into your FileMaker solution. Please refer to the Sample.fmp12 database that came with your DocuBin download for examples.<br />
<br />
* DocuBin - Add File ( Path ; File )<br />
* DocuBin - Add Folder ( Path )<br />
* DocuBin - Mark as Deleted ( Path )<br />
* DocuBin - Move File or Folder ( SourcePath ; DestinationPath )<br />
* DocuBin - Show in File Browser ( FolderPath )<br />
* DocuBin - Quick Search ( Term { ; Path } )<br />
* DocuBin - View Content ( ContentIDs )<br />
<br />
Note: To check the script result use GetValue ( Get ( ScriptResult ) ; 1 ). If the script returns 1 then it completed successfully. If it returns FALSE, use GetValue ( Get ( ScriptResult ) ; 2 ) for the error message.<br />
<br />
The 'Add' scripts are compatible with Web Publishing and FileMaker Server, and require the Scribe, License Check, and SuperContainer Companion Plugins to be installed in their respective locations:<br />
<br />
Web Publishing<br />
FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins<br />
<br />
FileMaker Server<br />
FileMaker Server/Database Server/Extensions<br />
<br />
Developer scripts cannot be run in demo mode.<br />
<br />
==Template Scripting==<br />
<br />
Template Scripts allows you to push documents stored in DocuBin to your FileMaker database using your very own scripts. For example purposes the following directions will use the external FileMaker database '''''Sample''''', which is included in your download. "Sample" has an external file reference to DocuBin, and one script named '''''Open Projects'''''.<br />
<br />
# Login to DocuBin with the developer account.<br />
# Select the menu option "DocuBin Settings…", which can be found under the menu '''''FileMaker Pro (Advanced)''''' on Macs, or under the menu '''''Help''''' on Windows.<br />
# Select Templates. Click the plus button [+] to create a new template.<br />
# Give your template a name, and create one label with the name ''Project Code''. The name of your label is important and will be used later.<br />
# Because you logged in as a developer, you should see a section called '''''Developer''''' at the bottom of the layout, with two fields '''''External FileName''''' and '''''External Script Name.''''' Enter ''Sample'' as the filename, and ''Open Projects'' as the script name.<br />
<br />
DocuBin is now configured to use the external script ''Open Projects'' from the database ''Sample'' whenever this template is used.<br />
# Close the Settings window, and open one of the files you have inserted into DocuBin. If you have not inserted any files yet, now would be a good time to start.<br />
# Select the template you just created. You should now see a link called '''''Open Projects''''', the label ''Project Code'', and a field where you can enter a Project Code. Type ''1000'' into this field.<br />
# Click the link '''''Open Projects'''''. If the Sample database is not open FileMaker will ask you to locate it. Remember, it is in your DocuBin download folder.<br />
# If everything worked right you should be looking at Project 1000 in the Sample database, and in the portal you should see the name of the file you were looking at in Docubin. Magic! Take a look at the script in the Sample database to see how it works.</div>Sarahhttp://docs.360works.com/index.php/MirrorSync_advanced_topicsMirrorSync advanced topics2014-02-05T19:20:41Z<p>Sarah: Reworked ESS instructions</p>
<hr />
<div>Welcome to the advanced section of the MirrorSync documentation! This guide will help you customize MirrorSync to suit your development needs, and provide detailed instructions for various situations. If you would like a good general overview of the software, please read through [[MirrorSync basic setup]] first!<br />
=== Deployment questions===<br />
<br />
====How do I uninstall MirrorSync?====<br />
To uninstall on Mac, run the 'Mac Uninstaller.pkg' that comes with the MirrorSync. On Windows, run 'C:\Program Files\360Works\Uninstall.<br />
<br />
====Installation for hosting providers====<br />
To install multiple instances of MirrorSync, choose the Hosting provider option in the installer. This is exactly the same as the regular installation process, except that it will allow you to rename the instance of MirrorSync. You can continue running the installer as many times as you like, once per client, renaming each instance to something unique. These copies can then be managed via the 360Admin utility, which is found either in your Program Files or Applications folder. When installing additional instances of the application, only a single Tomcat process will be installed which is shared by all of the MirrorSync instances.<br />
<br />
We recommend you use the installer. We at 360Works use the installer for our hosting clients as well, and find it easy to update and manage. If you are curious as to what the installer actually does, it modifies and adds the following:<br />
<br />
* Creates a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows that is readable and writeable.<br />
* Downloads and installs an instance of [http://tomcat.apache.org/download-60.cgi Tomcat 6] into that folder. (Only one copy of Tomcat is installed, regardless of how many copies of MirrorSync are running)<br />
* Copies and renames the installer's MirrorSync.war, which deploys the web app, as well as the other supporting material into the folder.<br />
* Adds a launch daemon in Library/LaunchDaemons in OS X, or creates a Windows Service to automatically start Tomcat.<br />
* Modifies the http.conf file for Apache to allow for URL redirection. If using Windows with IIS, we create an ISAPI filter or a URL Rewrite rule for the URL redirect.<br />
* Copies a lightweight Admin Utility JAR file to manage Tomcat to either C:\Program Files\360Works or /Applications.<br />
<br />
If upgrading from an older version of MirrorSync, we'll copy over the SyncData and remove the URL redirects for the old MirrorSync.<br />
<br />
If you prefer MirrorSync to be deployed to your own instance of Tomcat that you've set up, please note and follow these instructions:<br />
<br />
# Create a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows. Make sure that it is readable and writeable to the process that Tomcat is running as. This is where MirrorSync stores its private data including the internal sync database and the stored configurations. If you have a strong preference for locating this someplace else, because of disk space for example, set the '360directory' system property to point to some other path.<br />
# Rename the MirrorSync.war file to whatever name you'd like the instance to run as for your hosting customer, ie. 'CustomerXSync.war' If you decide to run multiple instances of MirrorSync with the same name (using multiple instances of Tomcat), you'll need to set '360directory' separately for each Tomcat instance, otherwise those multiple instances will overwrite each other's private data.<br />
# Drop that .war file into the webapps directory in your Tomcat instance.<br />
# Modify the the MirrorSync.xml context descriptor and set the administrative username and password for MirrorSync. In Tomcat 6, this file is automatically written to the Tomcat/conf/Catalina/localhost. If you are running Tomcat 7, the file is located in the webapps/MirrorSync/META-INF/context.xml file, or you can follow the instructions at http://tomcat.apache.org/tomcat-7.0-doc/config/host.html regarding copyXML to get the same behavior as Tomcat 6 (we recommend doing this, so that you don't lose the context.xml file every time the application is redeployed).<br />
# If necessary for your configuration, set up URL forwarding from IIS / Apache to your Tomcat connectors. [http://tomcat.apache.org/tomcat-6.0-doc/index.html See tomcat documentation on how to do this].<br />
<br />
==== Installing without a network connection ====<br />
The MirrorSync installer normally needs a network connection during the installation process. It uses this to download a copy of Apache Tomcat 6 from the Apache web site, as well as doing a network license check to validate the license key. If you are in an environment that has no outbound network capabilities, you can still install MirrorSync, but you'll need to follow these extra steps:<br />
<br />
# Contact support@360works.com and ask for a customized build of MirrorSync that does not need a network connection for license checking. Be sure to include your license key and registration information.<br />
# Manually create a new folder at /Library/360Works (on Mac) or C:\Program Files\360Works (on Windows).<br />
# Download Apache 6 from http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.36/bin/apache-tomcat-6.0.36.zip and place it into the 360Works directory.<br />
<br />
Now you should be able to run the installer without any network connection.<br />
<br />
==== Split server deployments ====<br />
If your FileMaker deployment is split onto multiple machines, we recommend installing MirrorSync on the FileMaker Server machine. This allows the download database feature in MirrorSync to work, which greatly simplifies deployment to end users. If you will not use the download database feature, and you do not plan on sending download URLs to your users, then install MirrorSync on the web server, for maximum speed during syncing.<br />
<br />
Regardless of which computer you install on, be sure that when you are configuring MirrorSync, you specify that the MirrorSync / FM Server machines are on different computers. This option is on the first screen in the new configuration process.<br />
<br />
====Does MirrorSync work with runtime versions of FileMaker Pro?====<br />
MirrorSync is untested and unsupported for use in this configuration. In addition, the legal licensing agreement for creating runtime versions of FileMaker specifically disallows any automated transfer of data between the runtime version and FileMaker Server. This restriction means that no sync process can legally be used to transfer data between the runtime edition and FileMaker Server, whether that is from a 3rd party or a home-grown automation process. Contact your FileMaker Business Account Manager for volume pricing on FileMaker Pro licenses.<br />
<br />
====What if I need to redeploy FileMaker Server?====<br />
If using a Mac, no additional steps should be required. However, if you are running Windows, you'll want to rerun the installer for MirrorSync.<br />
<br />
<div id="upgradeFrom1"></div><br />
====I am running MirrorSync 1. What do I need to do to upgrade to 2?====<br />
Any extra configurations or devices you purchased with MirrorSync 1 will carry over to MirrorSync 2 after purchasing the upgrade.<br />
<br />
# First, have all of your offline users run a sync. They will need to replace their offline files with new versions, so this will prevent them from losing any data.<br />
# MirrorSync 2 requires a creation timestamp field, in addition to the modification timestamp. Create that field if you do not already have one, and be sure to add it to all the MirrorSync layouts.<br />
# Run the MirrorSync installer. MirrorSync 1 configurations will not be preserved, so you'll need to create new configurations and distribute new copies of the files to your users. The good news is that since you already have all of your sync layouts ready to go, and also since MirrorSync 2 automatically detects foreign keys (requires FileMaker Server 12 or later), this shouldn't take much time at all.<br />
# Download new copies of the file for your users, and enjoy all the great features and speed of MirrorSync 2!<br />
<br />
=== Networking questions ===<br />
<br />
====Can MirrorSync send encrypted data? What about SSL enabled FMS?====<br />
<br />
Yes, it can. To make sure data is encrypted, you'll need a valid SSL certificate installed on the web server where MirrorSync is running. This will ensure that all plain-text data is sent and received encrypted with SSL. To sync container data using SSL, first set up FileMaker server as SSL enabled ([http://www.filemaker.com/downloads/documentation/fm12_security_guide_en.pdf see page 20 of these docs]). After doing so or if FileMaker Server is already is SSL enabled, check the SSL checkbox when configuring MirrorSync. <br />
<br />
If you get an error saying that you have a self-signed certificate, then you will need to follow the [[Custom SSL Certificate setup instructions]].<br />
<br />
<br />
====I need my database to be HIPPA compliant, what should I do with MirrorSync?====<br />
HIPPA compliance depends on a large number of requirements. However, one of those requirements is to transmit only encrypted data. See the question above if you experience difficulties. Please keep in mind that encryption is one piece of HIPPA compliance, so consult the [http://www.hhs.gov/ocr/privacy/ Department of Health and Human Services] for more information.<br />
<br />
<br />
====What ports are required for MirrorSync? Can I change them?====<br />
MirrorSync transmits container data on port 5003, which is the regular port for communication betwen FileMaker Pro and FileMaker Server. All other field types (text, number, date, time, timestamp) are transmitted using regular HTTP communication, which typically runs on port 80, or port 443 if SSL encryption is being used. These port numbers are set in your web server configuration (IIS on Windows or Apache on OS X), and can be customized to any value you prefer. A good way to test this is to test the FileMaker Web Publishing Engine - if the URL 'http://yourServer:somePort/fmi/xml/FMPXMLRESULT.xml?-dbnames' returns an XML list of database names, then it should work for MirrorSync as well.<br />
<br />
====Will MirrorSync work on a VPN?====<br />
Yes. MirrorSync runs over standard HTTP protocols (which are VPN compatible) for non-container data, and standard FileMaker protocols (which are also VPN compatible) for container data.<br />
<br />
====My solution is behind a firewall. Will MirrorSync still work?====<br />
MirrorSync communicates with FileMaker Server using a web viewer, so as long as the firewall allows standard HTTP traffic on port 80 (almost all firewalls are configured to allow this), all of your sync devices should be able to access it through the firewall. The exception to this is container fields. If you are syncing container fields, you will need to make sure that port 5003 (FileMaker's standard port) is open on the firewall, because the client needs to connect as a guest of the server to transfer container data.<br />
<br />
<div id="nat"></div><br />
<br />
==== Is MirrorSync compatible with Network Address Translation (NAT)? ====<br />
Yes. When configuring MirrorSync, select the option that says 'My internal and external IP addresses are different.' This will write the sync script so that if it detects it's running on the same LAN as MirrorSync, it will use the internal IP address, and if it's running outside the MirrorSync LAN, it will automatically switch to the external IP address.<br />
<br />
<br />
<br />
<br />
===Primary key / serial numbers===<br />
<br />
====What is the difference between 'MirrorSync-managed' and 'Developer-managed' primary keys? Do I need to change how I do my primary keys? Which one should I pick? ====<br />
Before answering this question, it's first necessary to explain why primary keys are a complex issue with synchronization. With traditional incrementing serial numbers, one database might have records numbered 1 through 10. Another database might have records 1 through 50. If we create a new record on the first database, it will get assigned the next number in the sequence (11). However, if we try to write that record to the second database, it will conflict with record 11 that already exists there. Here are several approaches to solving that problem:<br />
# '''Use Universally Unique Identifiers (UUIDs) as primary keys'''. These are typically long, 36-character strings that look like this: "D2EF9F69-5DEA-4FE3-9095-162C77F76FBF". They are sufficiently random to statistically eliminate the possibility of duplicate values. This makes them ideally for syncing databases - you can safely write records from one database to another without worrying about conflicting IDs. MirrorSync (and most other sync frameworks) supports UUIDs.<br />
# '''Combine a traditional serial number with some delimiter''', such as each user's initials or a file ID. This way, user 1 would have primary keys "1.1", "1.2", "1.3", and so on. User 2 would create primary keys "2.1", "2.2", "2.3", etc. This has the advantage of being shorter and more readable than UUIDs, but the added management consideration of assigning unique identifiers to each user. MirrorSync can manage this for you, as explained later.<br />
# A variation on the second solution would be to '''assign each user a particular numeric range''', so that user 1 generates primary keys in the range of 1-10,000; user 2 generates primary keys 10,001-20,000; and so on. This has the advantage of pure numeric values (instead of text), but the disadvantage of the possibility of conflicts if a user exceeds the expected number of records. MirrorSync can manage this approach as well.<br />
# A very different approach is to '''allow conflicting primary keys to exist on each separate database, without ever writing those primary keys to other databases'''. When record #11 is written from the first database to the second (in our original example), instead of being written with primary key 11, it is written with primary 51 (the next number in the sequence on the second database). This has the advantage of the shortest possible primary keys, which are pure numeric values, with no possibility of conflicts. It is also the way that the majority of existing databases are designed. MirrorSync supports this method (and is the only sync framework that does, to our knowledge). It creates an internal table to translate between the primary keys on all database that are syncing, so that when record #11 is later updated, MirrorSync knows to change record #51 in the second database. MirrorSync also re-writes foreign keys when they are written from one database to another, so that foreign keys that contained '11' on the first database will be re-written with '51' in the second database.<br />
<br />
Options 1, 2, and 3 are considered ''''Developer-managed'''', because MirrorSync writes the primary keys unmodified between the databases being synced. It is the developer's responsibility to pick some scheme that ensures that the same primary key is never used for different records on different databases. There are other variations on the same theme (ie. one database gets odd numbers and the other gets even numbers), but they all are treated the same by MirrorSync.<br />
<br />
Option 4 is considered ''''MirrorSync-managed'''.' The developer is not responsible for the uniqueness of primary keys across different databases; MirrorSync takes care of this for you.<br />
<br />
As to which you should pick, the answer is usually this: If your FileMaker database is currently using UUIDs, use developer-managed. If your database is written using traditional serial numbers, you should use MirrorSync-managed. However, if you need 'user-friendly' numbers for things like invoice numbers, job numbers, or check numbers, [[#writebacks|read the next FAQ]] on user-friendly serial numbers before making a decision.<br />
<br />
If you are building a new database and can use whichever approach you want, here are the relative advantages:<br />
* Serial numbers are more efficient because they are smaller. [[#What can I do to speed up syncing?|See the performance section of this documentation]] for more discussion on this.<br />
* UUIDs are easier to use if you need to ever sync or import manually without using MirrorSync, or switch to some other sync tool (which only support UUIDs).<br />
<br />
<div id="writebacks"></div><br />
<br />
====What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?====<br />
The problem with MirrorSync-managed serial numbers is that they are not suitable for user-visible numbers, such as invoice numbers. That's because the primary key will be different on one device than another. If you're using the primary key serial number as your invoice number, it is clearly a problem if your invoice number is different between your laptop and the server!<br />
<br />
There are several solutions to this problem. One of the first things to establish is whether your database uses a single field as both the primary key and the user-visible value (we'll refer to it as the 'invoice number'). It is always preferable (even when not syncing) to have these be separate fields from each other. Invoice numbers / job numbers / user visible numbers should NOT be what you use as a primary key in your database. Primary keys are internal database identifiers, and should not do double-duty as a user-readable value.<br />
<br />
If the fields are separate, the problem becomes simpler to solve, because you have the flexibility to change the value of the invoice number without breaking relationships. See the section below on write-back values for the recommended approach.<br />
<br />
If the same field is being used for the primary key and the invoice number, and if it is feasible to split this into two separate fields (one for relationships, and one for display/searching), you should do so. Unfortunately, this can sometimes be a very big job - creating the new field is easy, but then you either need to find every place that that field is used in the user interface and point it to the newly created invoice number field, or else you need to find every place that it is used in the relationship graph and re-point that to the newly created primary key field. If you do not want to do this, then see the section below on MIRRORSYNC_CLIENTID for the recommended approach.<br />
<br />
{{mbox <br />
| type = warning<br />
| text = <b>One mistake you should be careful to avoid is this:</b> If your database is currently designed with serial numbers for primary keys, do not try to short-cut the solution by simply creating a new UUID field and try to trick MirrorSync into using that as your primary key. MirrorSync won't re-number your foreign keys, which means that the wrong children records will point to the wrong parent records when the records are synced with the server.}}<br />
<br />
===== Write-back values for user-visible numbers =====<br />
Let's say that you have a UUID as your primary key field, as well as an invoice number field. Using the write-back approach, the invoice number field will be blank when a record is created in an offline file. When that invoice record is synced to the server, it will get assigned the next invoice number, and that number will be written back to the invoice number field on the offline file. This approach does not work unless the invoice number field is separate from the primary key.<br />
<br />
Advantages of this approach:<br />
* Invoice numbers are in a simple, short numeric sequence, just like they would be without syncing.<br />
<br />
Disadvantages:<br />
* The offline file does not get an invoice number until the record is synced for the first time.<br />
<br />
To use this approach, follow these steps:<br />
* If you do not already have a serial number field in your table, create one. If you have a serial number which is used as a primary key, that's usable. We'll call that field 'serialNumber' in our example.<br />
* Define your invoiceNumber field this way: <code>If( Get( MultiUserState ) = 2; serialNumber; "" )</code>. This will leave the invoice number blank when working offline, but fill it in when connected directly to the server.<br />
* In the primary key selection screen in MirrorSync, select invoiceNumber as the write-back field. This will cause MirrorSync to write invoiceNumber from the server back to the offline file when the record is first synced.<br />
* Your choice of MirrorSync-managed or Developer-managed is unaffected by this setting; pick appropriately depending on whether you are using serial numbers or UUIDs as your primary key.<br />
<br />
===== MIRRORSYNC_CLIENTID for user-visible numbers =====<br />
Let's say that you have a single serial number as your primary key, which is doing double-duty as an invoice number field. You can use the $$MIRRORSYNC_CLIENTID global variable to help. Using this approach, MirrorSync ensures that each file being synced gets assigned a unique sequential number, starting from 1. You can use this number in conjunction with a traditional serial number to create a unique number than can be used as a user-visible field as well as a primary key. The serial numbers will either be text (ie. "1.1", "1.2", "1.3"…) or numeric (10,001 for user 1, 20,001 for user 2, 30,001 for user 3…).<br />
<br />
Advantages of this approach:<br />
* Reasonably short user-visible numbers<br />
* IDs are assigned immediately upon record creation, without needing to wait for syncing<br />
<br />
Disadvantages:<br />
* Offline users must do an initial sync before they can create records.<br />
* Requires a startup script to run, which means it won't work with custom web publishing applications.<br />
* IDs are not sequential, so you can't assume that an ID with a higher value was created before or after another ID.<br />
* If you are using numeric version, limits users to creating a fixed number of records before they start conflicting.<br />
* If you are using text version, you must switch all primary key and foreign fields from 'number' type to 'text.'<br />
* Setup is a bit more complex than write-back fields.<br />
<br />
To use this approach, follow these steps:<br />
* Set the 'MirrorSync setup' script as your startup script. If you already have a startup script, call the 'MirrorSync setup' script from your existing script. This will set the $$MIRRORSYNC_CLIENTID global variable. This clientId field is stored in the MirrorSync table, and is assigned when the user does their first sync. Each synced database will get a unique, sequential clientId. Manually run the script now to set that global variable before proceeding.<br />
* We assume you have a serial field called 'serialField'. Start off by duplicating this field, to create a new field called 'serialField copy.'<br />
* Change serialField to an auto-enter calc. Uncheck the box that says 'Do not replace existing value'. Also make sure that the 'Prohibit modification of value during data entry' is unchecked. Set the formula to one of the following:<br />
For text keys, use this formula. This will result in primary keys that look like "1.1", "1.2", "1.3" from device 1, and "2.1", "2.2", "2.3" from device 2. Feel free to modify as desired. Be sure to change the field type from number to text. Also change all foreign keys that relate to it to text.<br />
<pre><br />
$$MIRRORSYNC_CLIENTID & "." & serialField copy<br />
</pre><br />
for numeric keys, use this formula. This will result in primary keys that look like "10001", "10002", "10003" from device 1, and "20001", "20002", "20003" from device 2. Replace whatever number you want instead of 10,000 to give a wider or narrower range of numbers.<br />
<pre><br />
$$MIRRORSYNC_CLIENTID * 10000 + serialField copy<br />
</pre><br />
* For primary key configuration in MirrorSync, select Developer-managed, and set 'serialField copy' as your primary key.<br />
<br />
<br />
<div id="compoundkey"></div><br />
<br />
==== How do I configure and use two foreign keys as a primary key? ====<br />
This is a common configuration for join tables in many-to-many relationships. In the primary key configuration screen, use the drop down menus to select the two foreign keys.<br />
<br />
Please keep in mind primary keys need to be unique. If using two foreign keys, there may be an instance where an error occurs about a duplicate node ID, since FileMaker is not validating the fields together and making sure they are always unique in a table. To avoid this, make sure:<br />
<br />
#Ensure that the combination of two foreign keys only ever occurs once in the database.<br />
#If you need to be able to have multiple join table records with the same foreign keys, add a regular serial number field to the join table and use that as the primary key, instead of the compound foreign keys.<br />
# The foreign key fields must both have the 'Not empty' validation in order to appear in the pull-down menu of eligible fields. If your join table needs to have foreign keys that may be empty, you should add a traditional single primary key to the table instead of using compound foreign keys as an identifier for MirrorSync.<br />
<br />
===Configuration questions===<br />
<div id="differentfile"></div><br />
==== Does MirrorSync need the databases being synced to be identical? ====<br />
No, not in MirrorSync 2. MirrorSync is able to sync between databases with completely different tables and fields from each other. In addition, it can sync just a subset of records, fields, and tables. If you are syncing different databases, for example a dedicated mobile file with a much larger server database, select the option 'Sync with a separate mobile file' (for FileMaker Go) or 'Sync with a separate server file' (for server-to-server sync). With this option selected, MirrorSync will allow you to match up your layout and field names with a simple drag and drop interface.<br />
<br />
====Why does MirrorSync need to know about foreign keys?====<br />
MirrorSync uses foreign keys for two purposes. If you are using MirrorSync-managed primary keys, then it needs to know about the foreign keys because it needs to rewrite them when it writes between databases (see the primary key section above).<br />
<br />
In addition, even if you're using developer-managed primary keys, MirrorSync needs to know about relationships so that it can sync parent tables before children tables. This allows validation rules that check referential integrity to work correctly.<br />
<br />
MirrorSync 2 adds a new feature that automatically detects foreign keys, if you are using FileMaker 12 or later, so this step should not add any time to the configuration process. If you are using FileMaker 11 AND you are using developer-managed primary keys AND if you do not have any referential integrity validation making sure that foreign keys point to valid parent records, you can safely skip this step.<br />
<br />
====I'm not seeing my databases from the Choose database button. What's happening?====<br />
Make sure XML publishing is enabled for the account you are using in MirrorSync. Also be sure the database is accessible from the machine you are installing MirrorSync on.<br />
<br />
To test the XML Web Publishing Engine, try going to the URL <code>http://yourServer/fmi/xml/FMPXMLRESULT.xml?-dbnames</code>. You should see an XML document listing the databases in FileMaker Server. If you do not, or find a 404 or 401 error, then the XML Web Publishing Engine may not be configured correctly. Contact FileMaker tech support for help getting this running.<br />
<br />
If there is an authentication required at that test URL, try disabling IIS authentication. FileMaker Server authenticates its password-protected databases; however, this method disables the IIS authentication layer. This will also disable authentication for other websites that are using IIS on that server.<br />
<br />
# From the Control panel, navigate to Administrative Tools > Internet Information Services (IIS) Manager<br />
# Select the website in IIS and choose Action > Properties<br />
# Navigate to the Directory Security pane, and select Edit for authentications. This button may differ in various Windows versions.<br />
# In the Authentications Methods pop up:<br />
#* Make sure Anonymous Access is enabled<br />
#* For Authenticated access, disable the authentication methods.<br />
# Press OK<br />
<br />
<br />
==== Configuration without FileMaker Pro Advanced ====<br />
<br />
Since FileMaker Pro does not have the ability to copy and paste tables, you'll need to follow these instructions to create the MirrorSync table.<br />
<br />
*Locate the XML schema that came with your MirrorSync download.<br />
*Open FileMaker Pro and navigate to File -> Import Records -> XML Data Source.<br />
*In the "Specify XML and XSL Options" window, choose the "File" radio button, then click "Specify...".<br />
*Navigate to your MirrorSync download folder and choose the MirrorSync.xml file from the XML Schema subfolder.<br />
*Click continue to bring up the Import Field Mapping window. <br />
*Open the "Target" drop down menu, and select "New Table ("MirrorSync")"<br />
*Verify that the source fields and target fields have been matched correctly.<br />
*Click import.<br />
<br />
After the table is created, you'll need to modify some of the fields:<br />
*Navigate to File -> Manage -> Database...<br />
*Navigate to the "Fields" tab, highlight the '''id''' field and click the "Options..." button.<br />
*Check the box next to "Serial Number." Set it to generate on creation.<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the boxes next to "Not Empty" and "Unique Value" then press OK.<br />
*Next, highlight the '''modstamp''' field and click the "Options..." button.<br />
*Check the box next to "Modification" and ensure that the drop down menu says "Timestamp (Date and Time)."<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the box next to "Not Empty" then press OK<br />
*Next, highlight the '''lastErrorMessage''' field and click the "Options..." button.<br />
*Navigate to the "Storage" tab and check the box next to global storage and press OK.<br />
*Repeat the last two steps to make '''webServerResponse, _gSync1, _gSync2, _gSync3, _gSync4, _gLastInsertTable''', and '''_gLastInsertResult''' all be global fields. <br />
*Finally, highlight the '''container''' field, and select "Container" from the "Type" drop down menu, next to the "Options..." button.<br />
You are now finished manually configuring your MirrorSync table. Click the OK button to close the database management window, and return to the MirrorSync configuration. (Be sure to save your changes!)<br />
<br />
<div id="separation"></div><br />
<br />
====Separation model / multiple file solutions====<br />
MirrorSync will work fine with multi-file solutions. You need to make sure that one of the files in your solution has a reference to every table that you want to sync (for separation model solutions, it is better to use the data file than the UI file, because MirrorSync stores some internal data in a new MirrorSync table that it creates in the file). When configuring MirrorSync, use this file. When using the MirrorSync download feature, be sure to select the multi-file option so that your offline users will receive all of the files for the solution.<br />
<br />
====How do I configure External SQL Source (ESS) tables?====<br />
MirrorSync supports ESS tables, but it's very slow compared to using MirrorSync to simply sync the database from the external SQL database into your FileMaker Server. We do not recommend ESS unless syncing is not an option for some reason.<br />
<br />
If you would like to use ESS tables, there are additional steps. First, set up sync layouts and primary keys, modification timestamps, and creation timestamps. Next, make a duplicate of your file and host it on FileMaker Server. Make the following changes to that duplicated file ONLY. We'll need to remove the ESS references to allow the user to access the data offline by turning the shadow tables into regular tables.<br />
<br />
* First, delete the data source. This is vital to preventing duplicate records and other artifacts of using ESS. Open File > Manage > External Data Sources and delete the OBDC data source.<br />
* Next, open the File > Manage > Database and navigate to the Tables tab. Copy any ESS tables. Then delete them. Make sure NOT to delete the table occurrences. After all the italicized tables are gone, paste the tables back in. This ensures they are local FileMaker files, not references to external data.<br />
* Make sure the primary keys, modification timestamps, and creation timestamps are correct. The primary key needs to be an auto-entered serial number or generated UUID.<br />
* Open the relationships tab in the File > Manage > Database and relink the missing tables.<br />
<br />
Now you're ready to configure MirrorSync! Start the configuration process, and select "Sync with a separate mobile file" on the third screen. Choose the file that was duplicated and modified, and continue with configuration as normal.<br />
<br />
====I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?====<br />
After converting your file, you'll need to edit the configuration and replace the MirrorSync script steps with ones generated for the FileMaker 12 file. This is due to the fact that the "Insert from URL" script step doesn't exist in FileMaker Pro 11.<br />
<br />
===Sync questions===<br />
<br />
==== Does MirrorSync work with timezones? ====<br />
Yes and No.<br />
<br />
For offline users who are syncing, Yes. When MirrorSync gets a list of all modifications, it will automatically detect the offline user's timezone and clock drift and compensate for it.<br />
<br />
For server-to-server sync, Yes. MirrorSync can detect FileMaker server's current time and compensate for it, just like it does for offline users.<br />
<br />
For non-syncing users connecting directly to FileMaker Server, No, not automatically. You'll need to perform a small work around to make this work. It gets a little complicated, so an example makes it more clear. Let's say your FileMaker Server is hosted in New York. A user in New York runs a sync at 12:30 PM Eastern Time. 30 minutes later, a user in San Francisco modifies a record on the server at 10 AM Pacific Time (1 PM Eastern Time). Due to the way that FileMaker Server works, that modification timestamp on the server in New York will say 10 AM. It will not be converted to Eastern Time, nor will FileMaker Server store any time zone information for anybody to tell that it was actually representing Pacific time. Essentially, it's just an incorrect value. When the next sync runs, MirrorSync is going to request records modified since the last sync at 12:30 PM, which is going to miss the change made by the San Francisco user, even though it was made since the last sync.<br />
<br />
The solution to this problem is very easy - it actually takes less time to do than it did to read that explanation! Let's say that your table contains a regular modification timestamp called 'Modification timestamp'. Create a new field called 'Host modification timestamp' (or whatever you prefer), and set it to auto-enter this calculated value (substituting your own field name in place of 'Modification timestamp'):<br />
<pre><br />
Let( x=Modification timestamp; Get ( CurrentHostTimeStamp ) )<br />
</pre><br />
<b>Be SURE to uncheck the box titled 'Do not replace existing value of field (if any)'.</b><br />
<br />
<b>Don't forget to add it to your sync layout, and REMOVE the regular modification timestamp from the sync layout!</b><br />
<br />
Use this field as the modification timestamp in the MirrorSync configuration process, instead of the regular modification timestamp.<br />
<br />
This works by using the FileMaker Server clock, instead of the user's clock, for the modification timestamp. Now, when the San Francisco user modifies a record at 10 AM Pacific Time, FileMaker Server will store 1 PM (the server's local time when that change was made) in the Host modification timestamp field, and MirrorSync will work with time zones correctly.<br />
<br />
====Why can't I transfer my database to another computer after I've synced it?====<br />
The MirrorSync server stores information about each device that syncs with it. This includes the primary key, as well as the count of modifications for that record on that particular device. If this file were to be synced from two different devices, this information would conflict and cause problems. If you do try to send a database to another device and sync it, an error message will appear and the sync will be prevented.<br />
<br />
====Can I share a device among multiple users?====<br />
Yes, but…<br />
<br />
If all users on that device log in with the same username, then it's <i>probably</i> OK, as long as you make sure that you are not using record level access privileges on the offline device that would grant different record access to different users.<br />
<br />
If you want each user who shares a device to log in with different usernames, then the solution is to put a separate copy of the file on the device, one for each user. Make sure that each user is only able to login to the file that is assigned to them.<br />
<br />
MirrorSync prevents multiple users with different usernames from sharing the same offline file, because if record level access privileges or script filters were configured differently for each user, that would lead to the sync process incorrectly deleting the wrong records on the server, which would be very bad.<br />
<br />
====Does MirrorSync sync container fields?====<br />
A:Yes, MirrorSync works with FileMaker container fields. Container fields do take longer than other field types to synchronize, so remove them from your sync layouts if you don't need them to be synced.<br />
<br />
<br />
====What about SuperContainer? Does MirrorSync work with that?====<br />
Yes, it does. However, with SuperContainer the approach is very different. Only the URLs are synchronized, not the actual files - they remain on the SuperContainer server. The advantage is syncing is very fast - there is no binary data being transferred. The disadvantage is that you'll only have access to the files stored in SuperContainer when you have working network access from your computer or iOS device.<br />
<br />
====Does MirrorSync sync external container fields?====<br />
Yes, MirrorSync works with external container fields. There are no extra steps to take when syncing with FileMaker Pro or FileMaker Server. If you are using external container fields on an iOS device, there are a few steps after configuration that are required.<br />
<br />
#Download a copy of the database from MirrorSync or FileMaker Admin<br />
#Open the copy on a computer, and navigate to File > Save a copy as...<br />
#Under the type drop down, choose "self-contained copy (single file)"<br />
<br />
This ensures the copy of the file embeds the containers into the file for easy use with FileMaker Go and offline functionality. <br />
<br />
PLEASE NOTE: there is an unfortunate behavior in FileMaker in this process: when saving the self-contained copy, FileMaker updates the modification timestamp for every record that has an external stored container field. That's not a problem normally, but when used with MirrorSync, it will make the initial sync very slow. The reason for this slowdown is due to MirrorSync assuming that all of those records have been modified on the client, so it writes all of the server data to the client (including the container data). <br />
<br />
The workaround for this is to uncheck the modification timestamp auto-entry before saving the self-contained copy, and then turn it back on after the copy has been saved. This modification timestamp behavior has been reported to FileMaker, Inc. and will hopefully be resolved soon.<br />
<br />
<br />
==== Why doesn't iOS 7 show a progress bar when I click the download link? Is anything happening? ====<br />
<br />
When you create a download link to share with users, the user will typically click on the link and be presented with a nice download window as expected. With iOS 6, you got a little progress bar that fills across the tab until the file downloads. Unfortunately, iOS 7 removes this download progress indicator, so it may look like nothing is happening after you click the download link. If this bothers you, we suggest filing a [http://www.apple.com/feedback/ feedback suggestion] with Apple directly. However, MirrorSync is actually doing a few things behind the scenes: once the link is triggered, it saves a copy of the hosted file on FileMaker Server and creates a backup of all the data, even if you have selected a clone. It then downloads the file to your device. This may take some time to create the back up and save a copy of the file depending on the size, but MirrorSync notes how long this takes in the log.<br />
<br />
====Does MirrorSync require users to sync with full access accounts?====<br />
<br />
No. MirrorSync requires a full access account only once: to paste in the table, scripts, and layout. When users run the sync, they will use their own user account privileges, with whatever access that grants them. See the '[[#Customizing MirrorSync|Customizing MirrorSync]]' section below for tips on restricting user accounts.<br />
<br />
====Does MirrorSync do conflict resolution?====<br />
Yes, MirrorSync has robust conflict detection and field-level merging (added in version 2). It will detect when the same record(s) are modified on both database and take action. There are two settings in the configuration client that will control how this works:<br />
<br />
* <b>Merge the changes together</b>: If MirrorSync sees that all of the changes made in the databases were to different fields (ie. firstName on the server and lastName on the client), it will automatically merge the changes together. It will not tell the user that a conflict occurred, it will just write the merged record to both the server and the client. If any changes were made to the same field, it is treated as a conflict and not merged.<br />
* <b>Flag the edit as a conflict</b>: MirrorSync will treat all modifications to the same record as a conflict, regardless of whether they were made to the same fields or different fields.<br />
<br />
If a conflict occurs, then MirrorSync will resolve it based on the next configuration option:<br />
* <b>User picks:</b> MirrorSync will present a web-based interface to the user, summarizing all conflicts and showing them exactly which fields were changed on both databases. It color-codes the actual sections of text that were changed, making it easy for even inexperienced users to make the best choice. The user is able to pick one entire record over another, pick individual fields from each record, and even manually edit the result to combine changes from both records. They also have the option to automatically select the most recent change (see next option).<br />
* <b>Most recent change wins:</b> MirrorSync will pick whichever record was last modified as the winner of the conflict. If Joe changes a record on his iPad at 3:00 PM, Kate changes the same record on her iPhone at 3:30 PM, and Tom changes the record on the server at 4:00 PM, then when Joe or Kate sync their database, Tom's record will be selected as the winner, regardless of when Joe and Kate do their sync.<br />
* <b>Hub always wins</b>: MirrorSync will always pick the value on the hub (typically FileMaker Server) as the conflict winner, regardless of other considerations. This is not generally recommended, because it is essentially first-sync wins behavior: Whoever syncs to the hub first will win conflicts with other offline users who modify the same record and sync. This setting can be useful if changes made by directly connected users should be given priority over offline, syncing users.<br />
* <b>Email administrator</b>: This is very similar to 'User picks', except that instead of the user who is doing the sync deciding, an e-mail is sent to the administrator email address specified in the configuration. The administrator can resolve the conflict using the same web-based user interface described above, after which the user will be able to sync normally.<br />
<br />
====Is MirrorSync transactional? What happens if the connection is lost while syncing?====<br />
MirrorSync is not 'transactional' in the strictest sense. If the connection is dropped during a sync, it is possible for records from one table to be written to the server, while records from another related table may not be written. However, MirrorSync keeps track of which records have been written and which ones have not, and it will resume from where it was on the next sync and complete everything as if the first sync had finished. If a record on the server cannot be written because it is being edited, the offline user will get a warning error message telling them this. MirrorSync will continue to retry that edit operation each time the sync script is run.<br />
<br />
====Can I use external authentication with MirrorSync?====<br />
Yes, MirrorSync supports externally authenticated accounts with no modifications. So long as the username on the local copy matches the username on the server, you can set up one password for local access and another for external authentication with the server. The passwords do not need to match between the local file and the hosted file.<br />
<br />
<div id="prepopulate"></div><br />
====Can I pre-populate my offline database to speed up initial sync?====<br />
Yes, but you need to do it carefully. The initial sync process has a lot of complexity under the hood. Selectively pre-populating the offline database is useful if you need to sync with an empty clone of a database that contains many records, because importing records is faster than syncing with an empty clone, especially when container fields are involved.<br />
<br />
There are two basic approaches here: You can either delete the data you don't want the user to have, or you can start with an empty clone and add the data you do want the user to have.<br />
<br />
The first approach is simpler - just make a copy of the database on the server (using the download feature of MirrorSync, or using FileMaker Server Admin if that's not an option), delete whatever data you don't want the user to have, and then treat it like you normally would. Keep in mind that if the user has record-level access to all the data, and if you haven't set up any filters in your MirrorSync customization script, then the initial sync will put those deleted records right back into the offline file, so make sure you only delete the records that the user won't get during the sync. Also keep in mind that records created in the last 4-24 hours (depending on your timezone) may be transferred during the initial sync, even if they have not been recently modified.<br />
<br />
The second approach is slightly more complex. Here are the steps to follow:<br />
* Start with an empty clone of your database file.<br />
* For each table that you want to pre-populate, import the records you want the user to have. Be sure to <b>uncheck</b> the box that says "Perform auto-enter options while importing". Make sure that you import most or all of the records that the user will have access to during the sync - it's faster for MirrorSync to sync an empty table than a table that has a small fraction of the desired records.<br />
* Open the MirrorSync script, and look for a line like this about 15 lines from the top: <pre>Set Variable [$$scriptCreationDate; Value:"2014-01-28 21:20:13"]</pre><br />
* The date in that line is the date that you copied and pasted the MirrorSync script steps. Make sure that date is at least 8 hours after the last creation timestamp of the records that you imported (or 24 hours if you're east of the Atlantic Ocean). If it's not, then change it.<br />
* Make sure that your offline users run a sync before making any database changes. This is especially important since we have altered the $$scriptCreationDate variable.<br />
<br />
=== Server-to-server sync ===<br />
<br />
==== How do I set up server-to-server syncing? ====<br />
For the most part, the process for setting up server-to-client sync is almost identical to server-to-server sync. Here are a few differences to be aware of:<br />
* If you will be syncing container fields across a Wide Area Network (WAN), both servers must have public IP addresses, because they each make HTTP calls to the other.<br />
* In the spoke configuration, you select 'copy or clone of existing file' or 'separate file.' If the first option is selected, you don't actually put the file on the other server during the setup process - go through the setup process, and when you're finished, save a copy or clone from the hub server using the MirrorSync download feature and upload it to the spoke server. If you select 'separate file', then you will need to have the file up and running on the spoke server during configuration.<br />
<br />
==== How do I run a server-to-server sync? ====<br />
You do not use the MirrorSync script from within FileMaker, like a server-to-client sync. Instead, use the 'sync' button in the MirrorSync admin utility. Once you've run the sync and are satisfied that everything is working correctly, you may enable auto-sync by checking that box and specifying the frequency to run the sync.<br />
<br />
==== How can I be notified of a problem that occurs during server-to-server sync? ====<br />
There is an administrative e-mail address that is set during MirrorSync configuration. If you set this, you will receive e-mail notifications whenever the sync fails (or succeeds, depending on what granularity you set admin e-mails to). These e-mails are sent via Amazon Web Services, and thus do not require you to configure an SMTP server.<br />
<br />
===Performance questions===<br />
<br />
====How well does MirrorSync perform on slow networks?====<br />
MirrorSync is very efficient over slow networks, because it sends very little data other than the actual record changes, and it transmits this information in large chunks, which is more efficient. There are 3 HTTP request at the beginning of the sync, and usually 2 HTTP requests per table that contains any modifications. For example, if you have a 20 table solution, and there are changes in 5 of the tables, it will usually take 13 HTTP requests (3 + 2*5) to complete the sync. By comparison, the FileMaker home page takes 65 HTTP requests to load in a web browser.<br />
<br />
<br />
====My file is very large, and I'm running out of memory during the sync====<br />
When syncing with FileMaker Server, there are two things that can run out of memory when syncing very large files - MirrorSync itself, and the FileMaker Web Publishing Engine. Of the two, it is far more likely for the WPE to be the culprit, so adjust that one first. You'll know if the WPE runs out of memory because it will completely stop serving requests and may not be able to be shut down without restarting the computer.<br />
<br />
To adjust the Web Publishing Engine memory allocation, edit this file:<br />
<pre><br />
Mac: /Library/FileMaker Server/Web Publishing/publishing-engine/jwpc-tomcat/bin/catalina.sh<br />
Windows: C:\Program Files\FileMaker\FileMaker Server\Web Publishing\publishing-engine\jwpc-tomcat\bin\catalina.bat<br />
</pre><br />
<br />
Look for a line that contains the text "-Xmx512M". The 512 is the amount of megabytes to allocate. Change to to a higher number, such as 1024 or 2048 (be sure to keep the 'M' after the number), save the file, and then restart the Web Publishing Engine using the FileMaker admin console. Then try the sync again. FileMaker Server 13 comes with this number pre-set to 2048, so it's probably not necessary to adjust it unless you're running FileMaker Server 10, 11, or 12.<br />
<br />
MirrorSync has a 512 megabyte allocation by default. This is typically sufficient for syncing change batches of around 200,000 records, although that number gets much smaller if the records contain a lot of information. Now divide that number by the number of devices simultaneously syncing - so if you expect up to 4 people to be syncing simultaneously, MirrorSync can probably handle up to 50,000 changes from each user with the default memory allocation. If you need more than that, you can increase the memory allocation by modifying the setenv file. The process is very similar to the WPE instructions, above, but the file is located here:<br />
<pre><br />
Mac: /Library/360Works/Applications/bin/setenv.sh<br />
Windows: C:\Program Files\360Works\Applications\bin\setenv.bat<br />
</pre><br />
<br />
====What can I do to speed up syncing?====<br />
MirrorSync is pretty fast without any special tweaking, but faster is always better. Here are some tips for squeezing out the best possible sync speed from MirrorSync:<br />
<br />
* SSD drives: MirrorSync does many thousands of tiny read and write operations when syncing large record batches. This type of usage will benefit greatly from the ultra-low latency of SSD drives. You will see a noticeable change in sync speed by installing MirrorSync on an SSD drive. You don't need to use an SSD for your entire hard drive - you can just put MirrorSync on the SSD by using a symbolic link in OS X or changing the install location on Windows. The SSD performance benefits will improve all sync operations, but it will be most noticeable when doing very small syncs with few or no changes, and initial syncs for large database with hundreds of thousands of records.<br />
<br />
* When MirrorSync fetches changed records from FileMaker Server, it requests all changes since 10 minutes prior to the last sync. This 10 minute overlap compensates for users whose clocks are slow. If you're using the Host modification timestamp trick outlined in the timezone section above, then the user clock doesn't matter, and you don't need this 10 minute overlap. You can get rid of it by editing the MirrorSync.xml file and change the 'fmServerOverlapSeconds' parameter from 600 (10 minutes) to 5 (5 seconds). The file is at:<br />
<pre><br />
Mac: /Library/360Works/Applications/conf/Catalina/localhost/MirrorSync.xml<br />
Win: C:\Program Files\360Works\Applications\conf\Catalina\localhost\MirrorSync.xml<br />
</pre><br />
<br />
* Use serial numbers instead of UUIDs, especially for large record sets with narrow tables. The difference between a 5 character serial number and a 36 character UUID adds up, especially when transferring large numbers of records that mostly consist of foreign keys, such as join tables. Don't make this change if you have a good reason for using UUIDs.<br />
<br />
* Container fields hold lots of data, require a guest connection to FileMaker Server over port 5003, and are sent individually instead of in batches like non-container data. If there are containers that you don't need to sync, remove them from the sync layouts. Removing all container fields will give much better sync performance, as well as eliminating firewall concerns, because MirrorSync does not need to connect as a guest of FileMaker Server.<br />
<br />
* If you want to just sync a subset of records, instead of the entire database, you can use either record level access privileges or scripted filters (see the customization section below for more details). Scripted filters are much, much faster then record level access privilege restrictions.<br />
<br />
* If you're on FileMaker 11, switch to 12 or later. All of MirrorSync's communication with FileMaker Server is via the XML Web Publishing Engine, and this was just not very fast in FileMaker Server 11. It is greatly improved in later versions of FileMaker Server.<br />
<br />
* Flag records instead of deleting them: MirrorSync 2 is very fast at detecting deleted records. However, it's always faster to sync edits and inserts than to scan for deletions, especially in large tables with more than 100,000 records. If you want to optimize performance, it might make more sense to flag records as being deleted instead of actually deleting them. That makes it into an edit operation, which is not affected by the number of records in the table.<br />
<br />
* If you are starting off with an empty clone, and the initial sync is taking a very long time, you can pre-populate the empty clone table. See the question: "Can I pre-populate my offline database to speed up initial sync?"<br />
<br />
===Customizing MirrorSync===<br />
<br />
====I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?====<br />
That's a three-part question with a three-part answer. Just <b>syncing certain tables</b> is very easy: When you're configuring the sync using the MirrorSync configuration utility, only include layouts corresponding to the tables that you want to sync.<br />
<br />
<b>Syncing certain fields</b> is also very easy: Just don't include any fields on your sync layouts except the ones that you want to sync.<br />
<br />
<b>Syncing certain records</b> is only slightly less easy: Edit the 'MirrorSync Customization' script and follow the instructions in the 'FindChanges' documentation there to constrain the found set to just the records you want to sync for the current user. Remember that the script will be running as the user doing the sync, so you can use the Get( AccountName ) function to determine which records are available. <b>Be careful regarding the use of $$globalVariables</b> - they will work correctly for the duration of the current sync, but they will not still be set on the next sync (except for $$MIRRORSYNC_USERTOKEN - see next question).<br />
<br />
Any records that are excluded by your search criteria will not be synced to the user. In addition, if those records were previously synced, they will be deleted from the user's device. This makes it very easy to create check-in / check-out workflows with MirrorSync, where jobs are synced to iPads, completed, and then deleted from the device.<br />
<br />
To test your customization script, go to the sync layout that you want to test, show all records, and run the MirrorSync customization script. If you don't get the results you expect, use the Script Debugger to tweak it.<br />
<br />
Another approach to limiting record access is with FileMaker's record level access restrictions. Any restrictions you place on the user's privilege set will be respected by MirrorSync, and the user will only receive those records when they do a sync. Records which were previously visible which switch to non-visible will be deleted on the next sync. Keep in mind that scripted record filters will be much faster than using record level access privileges.<br />
<br />
If you decide to limit the synced records, you may choose to distribute an empty clone to your users instead of a full copy of the database. That way, the initial sync will only pull the records into their offline file that they have access to on the database. Keep in mind that if they have access to many thousands of records, that could make the initial sync slower than if you distributed a full copy of the database that already contains all of the record data, and let the initial sync delete the extra records.<br />
<br />
====How can I filter records on a per-user basis if everybody is logging in with the same Filemaker account?====<br />
Use the $$MIRRORSYNC_USERTOKEN to accomplish this. This is a special global variable that MirrorSync passes from the client to the server when a sync runs. You can set this global variable to whatever you want on the client, and it will be set on the server so that the MirrorSync customization script can use it when searching for records. This global variable is the one exception to the 'no global variables' rule for server-side filtering, so use it any way you want. You'll notice that it is nested in a conditional in the MirrorSync customization script that sets it. That 'If' statement prevents it from being set on the server, which is important because that would override the value sent by the client.<br />
<br />
====How can I tell if a record created in FileMaker Go has been synced with the server?====<br />
During configuration, select any field as a write-back value (see [[#writebacks | write-back values]] in the primary key section, above). Make sure that value is only set to auto-enter a value on the server, by checking that <code>Get(MultiuserState) = 2</code>. If the field is blank, the record has not yet been synchronized. If the field contains a value, then it was either created on the server, or created in FileMaker Go and synced with the server.<br />
<br />
Another approach you can take is by modifying the didInsert section of the customization script (see next question), but the write-back approach is significantly faster when syncing.<br />
<br />
====How can I run a script on the server when a record is synchronized?====<br />
Maybe you want to send an e-mail to an administrator when a user completes a delivery, creates a request for a quote, or deletes a job in production. To do these types of operations, modify the MirrorSync customization script. There is a section in the script for 'DidUpdate', 'DidInsert', and 'WillDelete'. Make sure you modify those in the 'Hub' section - it's very rare that these should be modified on the spoke. In the relevant section of the script, check the current layout, and if it's the one where you want to take action, go ahead and do whatever you want in this section. You can freely go to other layouts, do searches / inserts / updates / deletions, send e-mails, or take any other action, as long as you finish the script on the same layout and record where you started.<br />
<br />
If MirrorSync detects that the record was modified as a result of a 'DidInsert' or 'DidUpdate' script, it will re-do the client search, taking into account any scripted record restrictions in the 'FindChanges' section. For example, if you want jobs to be removed from the user's iPad when a record on the 'SyncJob' layout has its status changed to 'Completed', take these steps:<br />
# Modify the 'FindChanges' to exclude records whose status is 'Completed' when Get(LayoutName) = "SyncJob". (To do this type of search in FileMaker, enter Find mode, Set the status field to 'Completed', Omit the current record/request, and then Constrain Found Set)<br />
# Modify the 'DidInsert' section to blank out the modification timestamp when Get(LayoutName) = "SyncJob".<br />
# Do the same thing in the 'DidUpdate' section.<br />
<br />
Now, whenever an offline user updates or inserts a record in the 'SyncJob' table, the script will blank out the modification timestamp. This triggers a change, which causes MirrorSync to re-do the search, which will exclude the complete job from the search, which will automatically remove it from the iPad.<br />
<br />
You might ask, why blank out the modification timestamp? The answer is that it actually doesn't matter what you do, as long as you make some change to the record at all. Blanking out the modification timestamp is a harmless change, because FileMaker will immediately replace the blank value with a new timestamp. You could just as well set any field on the record to its current value, or make some more meaningful change, such as filling in a date field with the data that the job was completed.<br />
<br />
====I don't want users to see any dialogs when the sync runs, can I prevent them from showing?====<br />
Yes, set the global variable $$SILENT_MODE to "1" in the MirrorSync customization script. This will prevent MirrorSync from showing any dialogs unless an error occurs, and for required information like login and conflict resolution.<br />
* If you would like to also skip the login dialog, AND if you know the user's password (ie. if it's stored in a users table) OR everybody is syncing with the same account, you can hard-code the $$MIRRORSYNC_USERNAME and $$MIRRORSYNC_PASSWORD values in the MirrorSync customization script. If these are both non-empty values, then MirrorSync will not prompt the user to enter their password.<br />
* If you would like to prevent the conflict resolution dialog from displaying, pick any option other than 'user decides' in the conflict resolution section of the MirrorSync configuration process.<br />
<br />
==== I don't want users to see the MirrorSync window at all when a sync runs. Can I prevent that from showing? ====<br />
If you are running MirrorSync on FileMaker Pro, then yes. Set the $$MIRRORSYNC_HIDE_WINDOW variable to 1 in the MirrorSync customization script. This will move the MirrorSync window off-screen, where the user cannot see it. This is not recommended for large sync operations that will take longer than a few seconds, because without that status display, users may think that their computer is frozen.<br />
<br />
If you are running MirrorSync on iOS, then this cannot be hidden. That is because MirrorSync needs to open a new window to manipulate the found set without losing the current selection, and new windows cannot be hidden offscreen on iOS devices. The $$MIRRORSYNC_HIDE_WINDOW variable will be ignored on iOS.<br />
<br />
==== Can I block other MirrorSync dialogs from being displayed to the user, or change the wording? ====<br />
Yes. Using the MirrorSync customization script, all dialogs, even error messages, can be suppressed or modified. Look towards the bottom of the MirrorSync customization script, and you will see a section that includes a dialog for each type of message that is displayed to users during a normal sync. You may freely customize the message displayed to the user, or the title of the buttons (but be sure that the first button still has the same meaning, and the second button still has the same meaning). If you want to hide the dialog from showing, you can disable the script step that displays it, but you must decide which option you would like to select, and exit the script with that button number. You can use this technique to display messages to your users in their preferred language.<br />
<br />
====Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?====<br />
Yes, absolutely. First of all, we recommend setting the 'MirrorSync setup' script as your startup script, or calling it from the startup script. This will check to see if the file is running offline, and whether it has ever been synced before. If not, it will prompt the user to do the initial sync. In addition, the MirrorSync setup script sets the $$MIRRORSYNC_CLIENTID global variable, which is necessary for some primary key strategies ([[#Primary key / serial numbers |see the Primary Key section above]]).<br />
<br />
Remember that the MirrorSync script is a regular FileMaker script that can be set to run at any time by the developer. For example, if there is a critical section of your application that requires users to see what the latest value is before they make a change, trigger the sync when the user navigates to that screen, and again when they are finished editing in that screen. You could make it so that checking a box, clicking a button, or any other condition that you choose can trigger the sync to happen.<br />
<br />
====Can MirrorSync run automatically every x seconds/minutes?====<br />
Yes, you can use an On Timer script to trigger this. However, keep in mind that when the script runs, it commits the current record and pops open a new window that could be open for a few seconds or longer. This could get annoying if it happens in the middle of something that the user is working on. For this reason, we recommend the approach in the previous question of linking your script sync operations to some user-initiated action. The exception to this is unattended computers - if you want to have a computer that is running MirrorSync all the time for purposes of having an extra copy of the database replicated, without a user working on it, then by all means go ahead and use an On Timer script step (and be sure to see [[#I don't want users to see any dialogs when the sync runs, can I prevent them from showing?|the FAQ above about]] disabling dialogs).<br />
<br />
==== Customizing the MirrorSync layout ====<br />
Feel free to make cosmetic changes to the 'MirrorSync' layout that is pasted into your solution. However, follow these tips before making changes:<br />
* Make sure you are able to successfully sync on FileMaker Pro and FileMaker Go before making customizations.<br />
* Make a backup copy of the unmodified MirrorSync layout first.<br />
* It is important that you preserve the tabs on the layout, and that the same fields remain in those tabs. The other thing to be careful about is that there are two 1x1 pixel web viewers on the MirrorSync layout. Make sure that those remain visible on the layout.<br />
* If the sync stops working after you make the changes, then you may have inadvertently lost the web viewers on the layout. Restore them from the backup copy of the layout.<br />
<br />
=== Licensing ===<br />
<br />
==== How does licensing and pricing work for MirrorSync? ====<br />
MirrorSync is completely free to use, with no limitations on features, for syncing FileMaker Server with a single copy of FileMaker Pro or FileMaker Go. You can optionally purchase additional server configurations or devices.<br />
<br />
The supported configuration types are:<br />
* FileMaker Server with FileMaker clients (Go or Pro)<br />
* FileMaker Server with FileMaker Server<br />
* FileMaker Server with any SQL database (Oracle, MySQL, and MS SQL Server are fully supported. You may also sync with any database with a JDBC driver).<br />
* SQL database with SQL database<br />
* SQL database with FileMaker clients (Go or Pro)<br />
<br />
Devices are sold in quantities of 1, 5, 10, 40, and unlimited. These can be purchased in addition to the single device that comes with MirrorSync for free.<br />
<br />
==== Is MirrorSync included in the 360Works Portfolio Bundle?====<br />
Yes. MirrorSync 2 is free for one device, but Portfolio Bundle (http://360works.com/portfolio) subscribers will receive an additional 10 device pack (for a total of 11 devices). Server-to-server configurations are not included in the Portfolio License, and must be purchased separately. There is also a special licensing program for FileMaker Business Alliance (FBA) members; contact us at support@360works.com for details.<br />
<br />
==== Is there a vertical market license type for MirrorSync? ====<br />
Yes. Contact support@360works.com for details about how this works.<br />
<br />
=== Miscellaneous questions ===<br />
<br />
====Is MirrorSync localized into any non-English languages? Does it work in other languages?====<br />
At this time, MirrorSync is only localized to English. Our current focus is on adding features, but we anticipate translating this into other languages when the product is more mature. If you would like to offer help with translation, please contact support@360works.com to let us know. You should still be able to add MirrorSync to your solution in other languages. See the previous section on customizing dialogs for tips on localizing your solution.<br />
<br />
====I only have an offline copy of my file left, and need to upload it back to the server. What do I do?====<br />
If necessary, you can re-upload an offline copy of the file to FileMaker Server and use it with MirrorSync. <b>Be sure to remove the "Client" record in the MirrorSync table</b>, and keep only the "Server" record. To do this, navigate to the MirrorSync layout, switch to the Debugging tab, and perform a find for "Server" in the type field. Select the inverse of the records found by pressing the pie icon in the status bar. Then, delete those other records.<br />
<br />
=== Troubleshooting/Known Issues ===<br />
<br />
==== The maximum number of users are currently using this copy of FileMaker Pro====<br />
<br />
[[File:MirrorSyncLicense.png|thumb|Example of error message]]<br />
<br />
There is a bug in FileMaker Pro and FileMaker Pro Advanced that may occur when pasting the MirrorSync script, or editing the MirrorSync script. This occurs due to the references found in the script, which will reference both the internal and external IP address. FileMaker then opens both of those references, which triggers the licensing server as two copies of FileMaker Pro. This error would occur for any script that contains both references to a single hosted file. <br />
<br />
There are two work arounds for this:<br />
<br />
# Upgrade your single user license to a volume license. You can contact FileMaker directly to upgrade your license if you have 5 or more copies.<br />
# Paste the script and let FileMaker close due the licensing error. The script will save appropriately, and should work correctly.<br />
<br />
If you require assistance on this issue, please let us know.<br />
<br />
====I keep getting a 102 'Field is missing' error, but I know my Sync layouts have all the right fields, what's wrong with it?====<br />
Make sure that the sync layouts are matching in both the offline and server copy. If you have repeating fields, make sure the fields show the maximum number of repetitions that are defined in the field definitions. In other words, if a field can repeat 5 times, make sure the repetitions in the inspector show 5.<br />
<br />
====Sync fails every time with error: Last sync failed: java.sql.SQLException: Error in table <Sync Layout Name>: Parse Error During Update 1: -1====<br />
This issue arises if a syncing solution has more than 998 syncing fields. The limit for the number of variables Filemaker will allow in a Let statement is 1000. During our Server <-> Client transactions, we require two variables for internal use, so the maximum syncing field limit per table is 998.</div>Sarahhttp://docs.360works.com/index.php/Send_us_a_bug_reportSend us a bug report2014-01-30T19:30:56Z<p>Sarah: Added a collapsible link to the log files</p>
<hr />
<div>== To send us a bug report ==<br />
# '''Reproduce the issue'''<br />
# Goto FileMaker Pro preferences ('''Important''' to do this '''BEFORE''' shutting down FileMaker)<br />
# Select Plugins tab<br />
# Select the plugin from list (highlight the line)<br />
# Click <code>Configure</code> below the list<br />
# Click <code>Report a Bug</code> button<br />
# Fill out and send the bug report<br />
<br />
This will send us the plugin log with entries showing the problem. <br />
<br />
<div class="mw-collapsible mw-collapsed toccolours">If you need to access the log files, click Expand to see all the locations: <br />
<div class="mw-collapsible-content">{{:Plugin_log_files}}</div></div></div>Sarahhttp://docs.360works.com/index.php/Plugin_log_filesPlugin log files2014-01-30T19:25:51Z<p>Sarah: </p>
<hr />
<div>== Log Locations ==<br />
<br />
===FileMaker Client===<br />
====OS X====<br />
<pre><br />
/Users/userName/Library/Logs/360Plugin Logs/360Plugins_XXXXX.log<br />
</pre><br />
<br />
====Windows====<br />
<pre><br />
XP or S2003: C:\Documents and Settings\<userName>\My Documents\360Plugin Logs\360Plugins_XXXXX.log<br />
Vista or S2008: C:\Users\<userName>\Documents\360Plugin Logs\360Plugins_XXXXX.log<br />
Windows 7, 8 alternative location: USER_HOME/360Works<br />
Plugin logs have also been seen on S2008 at: C:\Users\<userName>\360Works\360Plugins_FMAdvanced.log<br />
</pre><br />
<br />
Our plugins also write 360temp.log. This log should have an entry with the location of the plugin log file<br />
<br />
Windows:<br />
<pre><br />
C:\Windows\Temp\360temp.log<br />
</pre><br />
Mac:<br />
<pre><br />
/tmp/360temp.log<br />
</pre><br />
<br />
===FileMaker Server===<br />
====OS X====<br />
<pre><br />
/Library/FileMaker Server/Logs/360Plugin Logs/360Plugins_XXXXX.log<br />
</pre><br />
====Windows====<br />
<pre><br />
XP or S2003: C:\Documents and Settings\Default User\My Documents\360Plugin Logs\360Plugins_XXXXX.log<br />
Vista or S2008: C:\Users\Default User\Documents\360Plugin Logs\360Plugins_XXXXX.log<br />
Windows 7/2008R2 (32 bit): C:\Windows\System32\config\systemprofile\360Works<br />
Windows 7/2008R2 (64 bit): C:\Windows\SysWoW64\config\systemprofile\360Works<br />
</pre><br />
(Note: The 64 bit version of Windows 7/Windows 2008 R2 runs a 32 bit architecture on top of the 64 bit architecture, and system files that need to run in 32 bit compatibility mode are stored in C:\Windows\SysWoW64 instead of C:\Windows\System32)<br />
<br />
===Crash Logs===<br />
====OS X====<br />
If the problem involves a crash, we may also need you to send us a crash log. On Macintosh, the crash file is located here:<br />
<pre><br />
FileMaker 7: /Users/yourName/Library/Logs/CrashReporter/FileMaker.crash.log<br />
FileMaker 8/9: /Users/yourName/Library/Logs/CrashReporter/FileMaker Pro.crash.log<br />
</pre><br />
====Windows====<br />
On Windows, after a crash, sometimes there will be a Java crashlog file on your desktop called hs_err_pidXXXX.log, where the XXXX is a random number.<br />
<br />
Windows crash log locations:<br />
C:\Users\[Some User]\Microsoft\Windows\WER\ReportArchive<br />
or<br />
C:\ProgramData\Microsoft\Windows\WER\ReportArchive</div>Sarahhttp://docs.360works.com/index.php/MirrorSync_1MirrorSync 12014-01-30T19:13:44Z<p>Sarah: </p>
<hr />
<div>{{TOC limit}}<br />
<br />
==Overview==<br />
MirrorSync is a simple, elegant FileMaker synchronization product that connects FileMaker Server with FileMaker Pro and FileMaker Go. Users can sync the hosted file with their FMGo or Pro clients, go off network to make changes, and sync again when a connection is available.<br />
<br />
==Why use MirrorSync?==<br />
MirrorSync is designed to solve the problem of how to work productively on a hosted FileMaker database without being tied to FileMaker Server. If, for example, you have multiple users connecting to FileMaker Server over a wide area network (WAN) you could notice a substantial slowdown, as every change is immediately written back to FileMaker Server. MirrorSync allows each user to take a local copy of the database which would run on the users machine and not be affected by the WAN performance. The user could sync when they first came into the office, work on their local copy throughout the day, and sync at specified times (or on demand) to push and pull the latest data to the server.<br />
<br />
Another use case would be users who work in the field and may have limited or no connectivity to the FileMaker server network. The user could take a local copy on their iPad or iPhone, input the information from the field, and then sync when they regain a network connection. If the connection is spotty, they could even specify a one-way sync where their information is pushed to the server, but no data is pulled down, thus speeding up the process.<br />
<br />
== Requirements ==<br />
<br />
{{ mbox | text = Please note that the latest Java 1.6 Update for Mac OS X Lion or higher breaks Java Web Start Functionality. For instructions on how to resolve this issue, [http://www.youtube.com/watch?v=AcZMla7u0jc&hd=1 click here].}}<br />
<br />
* Server:<br />
** Windows 2003r2 or later, or Mac OS X 10.5 or later<br />
** FileMaker Server 11.0v3 or 12.<br />
* Configuration utility:<br />
** OS X 10.6 or later, or Windows 2007 with Java 1.6 or higher installed<br />
** FileMaker Pro 11 or 12 (FileMaker Pro Advanced is recommended and reduces setup steps, but not required. If you do not have FileMaker Pro Advanced, read [[#Q:_Is_FileMaker_Pro_Advanced_completely_necessary_for_configuration?|the FAQ on Is FileMaker Pro Advanced necessary for configuration?]]<br />
** NOTE: This is only required for one machine on the network<br />
* Sync Client:<br />
** Mac or Windows with FileMaker Pro 11 or 12 OR<br />
** FileMaker Go running on iPad, iPhone, or iPod Touch<br />
<br />
==MirrorSync With Hosting Providers==<br />
<br />
As of 1.25, MirrorSync supports hosting provider installations of MirrorSync.<br />
<br />
The following companies have indicated that they are set up or willing to configure their servers to host MirrorSync. If you'd like to be added to this list, please contact us at plugins@360works.com.<br />
<br />
* '''ODI Technologies''' ( http://www.oditech.com/ )<br />
* '''Michael Tinder, DataUp365''' ( http://dataup365.com/DU/ )<br />
* '''John May, Point in Space''' ( http://www.pointinspace.com/ )<br />
* '''Andrew McCallum, Niche IT Pty Lty''' ( http://www.nicheit.com.au/ )<br />
* '''Foxtail Technology''' ( http://www.foxtailtech.com/ )<br />
*'''NeoCode Software''' ( http://www.neocodesoftware.com )<br />
* 360Works can also host your database with MirrorSync, so [mailto:infobox@360works.com please contact us directly] about this service.<br />
<br />
To install multiple instances of MirrorSync, choose either the Hosting provider option on Mac, or hold down ALT on a Windows computer. This will allow you to name a new instance of MirrorSync and install multiple copies. These copies can then be managed via the 360Admin utility, which is found either in your Program Files or Applications folder. When installing additional instances of the application, only a single Tomcat process will be installed which is shared by all of the MirrorSync instances.<br />
<br />
We strongly recommend you use the installer, even for hosting providers. We at 360Works use the installer for our hosting clients as well, and find it easy to update and manage. If you are curious as to what the installer actually does, it modifies and adds the following:<br />
<br />
* Creates a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows that is readable and writeable.<br />
* Downloads and installs an instance of [http://tomcat.apache.org/download-60.cgi Tomcat 6] into that folder. (Only one copy of Tomcat is installed, regardless of how many copies of MirrorSync are running)<br />
* Copies the installer's MirrorSync.war which deploys the web app, as well as the other supporting material into the folder.<br />
* Adds a launch daemon in Library/LaunchDaemons in OS X, or creates a Windows Service to automatically start Tomcat.<br />
* Modifies the http.conf file for Apache to allow for URL redirection. If using Windows with IIS, we create an ISAPI filter for the URL redirect.<br />
* Copies a lightweight Admin Utility JAR file to manage Tomcat to either Program Files/360Works or Applications.<br />
<br />
If upgrading from an older version of MirrorSync, we'll copy over the SyncData and remove the URL redirects for the old MirrorSync. <br />
<br />
If you prefer MirrorSync to be deployed to your own instance of Tomcat that you've set up, please note and follow these instructions:<br />
<br />
# Create a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows. Make sure that it is readable and writeable to the process that Tomcat is running as.<br />
# Rename the MirrorSync.war file to whatever name you'd like the instance to run as for your hosting customer, ie. 'CustomerXSync.war'<br />
# Drop that file into the webapps directory in your Tomcat instance.<br />
# Modify the the MirrorSync.xml context descriptor and set the administrative username and password for MirrorSync. In Tomcat 6, this file is automatically written to the Tomcat/conf/Catalina/localhost. If you are running Tomcat 7, the file is located in the webapps/MirrorSync/META-INF/context.xml file, or you can follow the instructions at http://tomcat.apache.org/tomcat-7.0-doc/config/host.html regarding copyXML to get the same behavior as Tomcat 6 (we recommend doing this, so that you don't lose the context.xml file every time the application is redeployed).<br />
# If necessary for your configuration, set up URL forwarding from IIS / Apache to your Tomcat connectors. [http://tomcat.apache.org/tomcat-6.0-doc/index.html See tomcat documentation on how to do this].<br />
<br />
==Important MirrorSync Information==<br />
Before moving further in MirrorSync, there are a few important points you need to know about. MirrorSync is a web application, accessed on client machines through a FileMaker Web Viewer. MirrorSync communicates to FileMaker Web Publishing Engine using XML to push and pull data to FileMaker Server. To configure and run MirrorSync, follow the instructions in the configuration utility to modify the hosted copy of the database you wish to sync. User will then download local copies of the hosted database and run the MirrorSync script to sync the local copy to their devices and the server.<br />
<br />
Distributing files is easy. You can either download a copy of the file from FileMaker Server, or MirrorSync, or create a download link. The download link is available to users of version 1.5 and above, and can create a revocable link to download a copy directly to a mobile device or computer. Click Download Database, and choose Create Link. Once you've downloaded the local database, you can make copies of this file, email the file, and use DropBox to distribute the offline copy to other users, iPads, and iPhones. '''When distributing copies, MAKE SURE to not run the sync script in the database!''' Once the sync script is run for the first time, the database is linked to your device's MAC address. Using a previously synced file on devices with different MAC addresses will result in errors. To get a copy of the file that is not linked to any device, simply navigate to your MirrorSync server address, login to the main screen, and choose "Download Database". You'll download a new copy that you can then email to other devices. You can also simply revisit the download link provided.<br />
<br />
'''After distribution, it is very important that you run the MirrorSync script before making any changes.''' This links the local copy to your device and ensures that you have the most recent information from the hosted database. During the initial sync, information from the hosted database takes precedence, so any changes you've made will be reverted.<br />
<br />
Devices cannot sync simultaneously. If a user gets a "Sync in Progress" message, they will need to try again in a few seconds to allow the first sync to finish.<br />
<br />
== Preparing your database for use with MirrorSync ==<br />
<br />
MirrorSync only supports sync with a single-file database, so if you have multiple files, create a new table with external table references to the other files.<br />
<br />
Be sure that XML extended privilege is enabled in FileMaker Pro. Choose this option under File > Manage > Security… Double click the FileMaker user, and choose Edit… from the Privilege Set.<br />
<br />
http://demo.360works.com/wiki/image002.png<br />
<br />
Make sure the Access via XML Web Publishing option is enabled and has a checkmark. Please note that this screen is different in FileMaker 12.<br />
<br />
Most tables that you would like to synchronize need to have a unique identifier, also known as a primary key. This can either be a sequential serial number, a universally unique identifier (UUID) generated with the new FileMaker 12 Get(UUID) function, or any other value that is guaranteed to be unique, non-empty, and unchanging for every record. If you are using UUID primary keys, it is important that you do NOT check the box prohibiting modification of these values -- for serial numbers this is irrelevant and syncs will work either way. The exception for this requirement is many-to-many join tables, which often do not have a primary key, and instead have two foreign keys linking them to primary keys in other tables. It is OK if these tables do not have primary keys.<br />
<br />
Every table (including join tables) must have a timestamp field which is set to auto-enter a modification timestamp.<br />
<br />
You should create a new layout for each table that you plan on synchronizing. Be sure to include the modification timestamp, primary key, and any fields that you want to synchronize. Be sure to NOT include summary fields, global fields, and unstored calculations. These will make synchronization slower. These are easy to spot, because if you enable the 'View->Show->Quick Find' menu in FileMaker, those field types will either have a yellow magnifying glass, or no magnifying glass. Remove those fields from the layout, and keep the ones with the green magnifying glass.<br />
<br />
http://demo.360works.com/wiki/greenglass.png<br />
<br />
MirrorSync checks with the initial sync which fields are read or writeable. If you have options selected that may prohibit writing to a field, MirrorSync may not be able to sync those fields appropriately. These options include "Prohibit modification of value during data entry" and "Validated by Calculation" under the options section for a field.<br />
<br />
Please remove or rename fields that have parentheses ( ) or square brackets [ ] . These fields are incompatible with MirrorSync. <br />
<br />
Host the database on FileMaker Server. Open the file as a guest with FileMaker Pro Advanced, using a full access account.<br />
== Configuring MirrorSync without FileMaker Pro Advanced ==<br />
<br />
=== Steps to manually import MirrorSync tables in FileMaker Pro ===<br />
*Locate the XML schema that came with your MirrorSync download.<br />
*Open FileMaker Pro and navigate to File -> Import Records -> XML Data Source.<br />
*In the "Specify XML and XSL Options" window, choose the "File" radio button, then click "Specify...".<br />
*Navigate to your MirrorSync download folder and choose the MirrorSync.xml file from the XML Schema subfolder.<br />
*Click continue to bring up the Import Field Mapping window. <br />
*Open the "Target" drop down menu, and select "New Table ("MirrorSync")"<br />
*Verify that the source fields and target fields have been matched correctly.<br />
*Click import.<br />
<br />
=== Steps to configure your new MirrorSync table ===<br />
*Navigate to File -> Manage -> Database...<br />
*Navigate to the "Fields" tab, highlight the "id" field and click the "Options..." button.<br />
*Check the box next to "Serial Number." Set it to generate on creation.<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the boxes next to "Not Empty" and "Unique Value" then press OK.<br />
*Next, highlight the "modstamp" field and click the "Options..." button.<br />
*Check the box next to "Modification" and ensure that the drop down menu says "Timestamp (Date and Time)."<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the box next to "Not Empty" then press OK<br />
*Finally, highlight the "container" field, and select "Container" from the "Type" drop down menu, next to the "Options..." button.<br />
<br />
You are now finished manually configuring your MirrorSync table. Click the OK button to close the database management window, and return to the MirrorSync configuration. (Be sure to save your changes!)<br />
<br />
<br />
==MirrorSync Quick Start Tutorial: Syncing the Demo File==<br />
MirrorSync comes with a fully featured demo. You may use the demo for your own files, or walk through a sample configuration below. The only demo limitation is that once you have created an offline copy of the database, that particular copy can only sync for 24 hours. You can renew this 24 hour window at any time by downloading a new offline copy from the server.<br />
<br />
MirrorSync ships with two example files: "Contact Management.fp7" and "Contact Management.fp12", along with a MirrorConfig.txt file. These files are copies of the Contact Management Starter Solution from FileMaker Pro 11. The only changes that have been made are the addition of the table generated by the MirrorSync Configuration Utility.<br />
<br />
To use the demo file:<br />
* Host the file on FileMaker Server<br />
* Run the appropriate Mac Installer.app or Windows Installer.jar<br />
* On the client machine, navigate to the URL provided at the end of the installation to download the MirrorSync utility. Be sure to match the capitalization of the word 'MirrorSync' in the URL.<br />
* Run the configuration utility using the username and password you created during installation. From the starting screen, click import and choose the configuration file (MirrorConfig.txt) from your download.<br />
<br />
http://demo.360works.com/wiki/ImportConfiguration.png<br />
<br />
* With the new configuration selected, click "Edit" from the main screen and proceed through the configuration utility. If using a three-machine FileMaker Server deployment, be sure to enter the host name of the web server. Otherwise, use 'localhost'. Be sure the "Contact Management" database that you hosted on FileMaker Server is selected, then click "Next" through the next six configuration screens. On the final screen, copy the scripts, layouts, and steps as indicated.<br />
<br />
http://demo.360works.com/wiki/ScriptStepChange.png<br />
<br />
* Download the file and run the MirrorSync script. This is a local copy of the FileMaker file and is linked with your current machine during the initial sync. To sync this file with multiple devices, follow the steps below for a custom configuration.<br />
<br />
==MirrorSync Setup Tutorial: Custom Configurations==<br />
In this tutorial, we'll walk through a MirrorSync configuration from start to finish, using the Contact Management.fp7 FileMaker Starter Solution. If you are using FileMaker 12 and would like to follow along, you can download a converted file at <br />
http://mirrorsync.360works.com/static/Contact%20Management.zip<br />
<br />
1) Prepare the file. This involves:<br />
- enabling the Access via XML Web Publishing extended privilege set in File > Manage > Security<br />
- ensuring that the database is contained in a single file<br />
- ensuring that each table has a primary key field, either with an auto-entered, unique serial number or UUID<br />
- ensuring that each table has a modification timestamp field, also set to auto-enter<br />
- creating a new "sync" layout for each base table (not table occurrence). The layout should only contain those fields that should be synched. This means no global fields, summary fields, or unstored calculations. If your solution has repeating fields, make sure to show all of the repetitions on the layout.<br />
<br />
2) Host the file on your FileMaker Server and run the MirrorSync installer. If you have a multiple machine deployment, run the installer on the machine where the web publishing engine is running. Make note of the URL at the end of the installation process.<br />
<br />
3) On your client machine, navigate to the MirrorSync URL and launch the MirrorSync Client. Follow the instructions in the configuration utility. This involves setting the primary keys and relationships, choosing the layouts to sync, confirming the fields, and inserting the table, script, and layout that MirrorSync generates. If you get stuck, look for the blue question marks - they have helpful tooltips.<br />
<br />
4) During the final screen of the configuration, MirrorSync will generate a table, script, layout, and script steps for synching. Copy and paste these into the hosted database (if you don't have FileMaker Pro Advanced, you'll need to import the XML for the table). Once these changes are made, click finished.<br />
<br />
5) From the MirrorSync Dashboard, choose the correct configuration and click "Download Database". This will download a copy of the database to your local machine. Keep in mind that after the initial sync this copy is tied to your device. If you would like to have the database on multiple devices, you'll need to navigate to the server address on that device, launch the client, and download the database directly, or download a fresh copy of the database and email it to the device.<br />
<br />
6) Before making any local changes, run the MirrorSync script.<br />
<br />
==Syncing==<br />
<br />
To sync changes to the server copy, simply run the MirrorSync script. This script is attached to the button on the MirrorSync layout, but users may choose to attach it to whatever is required. Be sure to sync once before making changes to assure that both copies are identical.<br />
<br />
Please note: if the database has multiple access accounts with different privilege sets, make a new copy for each user. Do not sync an offline copy of the database to the server using multiple accounts.<br />
<br />
==Main Screen==<br />
<br />
http://demo.360works.com/wiki/mainscreen.png<br />
<br />
After configuration, users can view information about current sync configurations. The left window displays all the current sync configurations. Users may Add new sync configurations, edit existing ones, duplicate, or delete them. If a sync with MirrorSync has been set up on another server, that configuration may be imported using the Import button.<br />
<br />
If a sync configuration needs to be changed, there are a couple of things to keep in mind. Choose Edit… from the Main Screen and walk through the configuration again. After making the changes required, be sure to delete everything in the MirrorSync script '''first''' and then paste in the new script steps. After walking through the configuration utility, make a fresh copy of the database and run the MirrorSync script again.<br />
<br />
The right window displays information about the currently selected sync and the option to run the sync script.<br />
<br />
The bottom window displays the log for MirrorSync.<br />
<br />
==Updating MirrorSync==<br />
{{ mbox | text = Please note that the updating process is different for hosting providers. [[MirrorSync for Hosting Providers | Please see this page for details.]]}}<br />
<br />
To update MirrorSync to a new version:<br />
<br />
# Download the new version from the website<br />
# Run the installer included in the download on the server<br />
<br />
After installing the new version, users with copies of offline files will be able to continue syncing. Occasionally, the script steps or the table may change in new builds. To check if there are new scripts to run, choose edit from the Main Screen. Keep pressing Next until you get to the final screen, where you copied the layouts, tables, and scripts into the hosted file. If there is an exclamation mark next to a step, hover over it and read the tooltip. You may need to replace the scripts in your solution to take advantage of a new feature, or to solve an issue in an older version.<br />
<br />
Remember, users with older offline files will be able to continue syncing. But to take advantage of the update, simply recopy the elements as directed on the screen and redistribute the offline files. There is no need to delete the configuration.<br />
<br />
If there are issues after upgrading, try restarting the Web Publishing Engine.<br />
<br />
== Frequently Asked Questions ==<br />
===Deployment and installation questions===<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: How_should_MirrorSync_be_installed|How should MirrorSync be installed?]]<br><br />
[[#Q: How do I upgrade MirrorSync to a new version?|How do I upgrade MirrorSync to a new version?]]<br><br />
[[#Q: Are plug-ins required?|Are plug-ins required?]]<br><br />
[[#Q: I had to restart the Web Publishing Engine on FileMaker Server and now the MirrorSync configuration utility is not working! What do I do?|I had to restart the Web Publishing Engine on FileMaker Server and now the MirrorSync configuration utility is not working]]<br><br />
[[#Q: What ports are required for MirrorSync? Can I change them?|What ports are required for MirrorSync? Can I change them?]]<br><br />
[[#Q: Will MirrorSync work on a VPN?|Will MirrorSync work on a VPN?]]<br><br />
[[#Q: Can MirrorSync send encrypted data? What about SSL enabled FMS?|Can MirrorSync send encrypted data? What about SSL enabled FMS?]]<br><br />
[[#Q: I need my database to be HIPPA compliant, what should I do with MIrrorSync?|I need my database to be HIPPA compliant, what should I do with MIrrorSync?]]<br><br />
[[#Q: My solution is behind a firewall. Will MirrorSync still work?|My solution is behind a firewall. Will MirrorSync still work?]]<br><br />
[[#Q: Can MirrorSync sync between two FileMaker Servers?|Can MirrorSync sync between two FileMaker Servers?]]<br><br />
[[#Q: Does MirrorSync work with runtime versions of FileMaker Pro?|Does MirrorSync work with runtime versions of FileMaker Pro?]]<br><br />
[[#Q: I have a three-machine FileMaker Server deployment. How do I install MirrorSync?|I have a three-machine FileMaker Server deployment. How do I install MirrorSync?]]<br><br />
[[#Q: Does MirrorSync support ESS tables?|Does MirrorSync support ESS tables?]]<br><br />
[[#Q: How do I uninstall MirrorSync?|How do I uninstall MirrorSync?]]<br><br />
[[#Q: What if I move servers, change my hostname, or IP?|What if I move servers, change my hostname, or IP?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: How should MirrorSync be installed?====<br />
A: Run either the Mac Installer.pkg or the WindowsInstaller.exe to install the MirrorSync application on the server. Your server can be separate from the Web Publishing Engine, beginning with version 1.5, but must have a Web Server such as IIS or Apache.<br />
<br />
After installation is finished, a message will be displayed pointing to the address where MirrorSync can be configured. Typically the address will display as http://servername/MirrorSync, where servername is replaced with the address of the server. Please keep in mind that the address requires the correct capitalization. From a client computer, navigate to that address to launch the configuration utility.<br />
<br />
====Q: How do I upgrade MirrorSync to a new version?====<br />
To upgrade to a new version, run the new install file (Mac Installer.pkg or WindowsInstaller.exe) and select Upgrade.<br />
<br />
====Q: Are plug-ins required?====<br />
A: No, the only software to install anywhere is the MirrorSync server application, which is installed on the FileMaker Web Publishing Engine. You can send a copy of the FileMaker database to anybody with a copy of FileMaker Pro, and they will be able to run the sync script.<br />
<br />
====Q: Can MirrorSync send encrypted data? What about SSL enabled FMS?====<br />
<br />
A: Yes, it can. To make sure data is encrypted, you'll need a valid SSL certificate installed on the web server where MirrorSync is running. This will ensure that all plain-text data is sent and received encrypted with SSL. To sync container data using SSL, first set up FileMaker server as SSL enabled ([http://www.filemaker.com/downloads/documentation/fm12_security_guide_en.pdf see page 20 of these docs]). After doing so or if FileMaker Server is already is SSL enabled, check the SSL checkbox when configuring MirrorSync. <br />
<br />
If you get an error saying that you have a self-signed certificate, then you will need to follow the [[Custom SSL Certificate setup instructions]].<br />
<br />
====Q: I need my database to be HIPPA compliant, what should I do with MIrrorSync?====<br />
A: HIPPA compliance depends on a large number of requirements. However, one of those requirements is to transmit only encrypted data. See the question above if you experience difficulties. Please keep in mind that encryption is one piece of HIPPA compliance, so consult the [http://www.hhs.gov/ocr/privacy/ Department of Health and Human Services] for more information.<br />
<br />
====Q: What ports are required for MirrorSync? Can I change them?====<br />
MirrorSync transmits container data on port 5003, which is the regular port for communication betwen FileMaker Pro and FileMaker Server. All other field types (text, number, date, time, timestamp) are transmitted using regular HTTP communication, which typically runs on port 80, or port 443 if SSL encryption is being used. These port numbers are set in your web server configuration (IIS on Windows or Apache on OS X), and can be customized to any value you prefer. A good way to test this is to test the FileMaker Web Publishing Engine - if the URL http://yourServer:somePort/fmi/iwp works for you, then it should work for MirrorSync as well.<br />
<br />
====Q: Will MirrorSync work on a VPN?====<br />
Yes. MirrorSync runs over standard HTTP protocols (which are VPN compatible) for non-container data, and standard FileMaker protocols (which are also VPN compatible) for container data.<br />
<br />
====Q: My solution is behind a firewall. Will MirrorSync still work?====<br />
A: MirrorSync communicates with FileMaker Server using a web viewer, so as long as the firewall allows standard HTTP traffic on port 80 (most firewalls are configured to allow this), all of your sync devices should be able to access it through the firewall.<br />
<br />
====Q: Can MirrorSync sync between two FileMaker Servers?====<br />
A: No, MirrorSync depends on web viewers and scripts steps that are only available in regular FileMaker Pro. You can sync between FileMaker Pro and FileMaker Server, but not between FileMaker Server and FileMaker Server. If this feature is important for you, please e-mail us and let us know: plugins@360works.com<br />
<br />
====Q: Does MirrorSync work with runtime versions of FileMaker Pro?====<br />
A: MirrorSync is untested and unsupported for use in this configuration. In addition, the legal licensing agreement for creating runtime versions of FileMaker specifically disallows any automated transfer of data between the runtime version and FileMaker Server. This restriction means that no sync process can legally be used to transfer data between the runtime edition and FileMaker Server, whether that is from a 3rd party or a home-grown automation process. Contact your FileMaker Business Account Manager for volume pricing on FileMaker Pro licenses.<br />
<br />
====Q: I have a three-machine FileMaker Server deployment. How do I install MirrorSync?====<br />
A: While MirrorSync can be installed on whatever machine is most convenient, we recommend that you install MirrorSync in the same location as FileMaker Server, as that will enable the Download Database functionality in MirrorSync. Please keep in mind you can always download the most recent version of the file via the FileMaker Server Admin Console. If that machine does not have a Web Server installed, such as Apache or IIS, your MirrorSync URL will be a direct URL such as http://360works.com:42424/MirrorSync.<br />
<br />
====Q: Does MirrorSync support ESS tables?====<br />
A: Yes! To use MirrorSync with ESS tables, there are additional steps. First, configure MirrorSync in its entirety. You should be able to select your ESS tables and files in the configuration utility. After you have pasted the last script step, download a copy of the file as usual. <br />
<br />
At this point, you need to make some modifications for the file to work offline. Open the downloaded copy, and make the following modifications to the local copy ONLY! Do not run the sync yet.<br />
<br />
* First, delete the data source. This is vital to preventing duplicate records and other artifacts of using ESS. Open File > Manage > External Data Sources and delete the OBDC data source.<br />
* Next, open the File > Manage > Database and navigate to the Tables tab. Copy any ESS tables. Then delete them. Make sure NOT to delete the table occurrences. After all the italicized tables are gone, paste the tables back in. This ensures they are local FileMaker files, not references to external data.<br />
* Make sure the primary keys and modification timestamps are correct. The primary key needs to be an auto-entered serial number or generated UUID.<br />
* Open the relationships tab in the File > Manage > Database and relink any missing tables. <br />
<br />
You can now distribute this file for synchronization to your users. Make a copy of this file and send it to each user who needs a copy. These copies are then ready for synchronization.<br />
<br />
====Q: How do I uninstall MirrorSync?====<br />
A: To uninstall, first stop the Web Publishing Engine. After that, run the original install file (Mac Installer.app or WindowsInstaller.exe) and select Uninstall.<br />
<br />
====Q: What if I move servers, change my hostname, or IP?====<br />
A: To move a MirrorSync installation:<br />
<br />
# First, export your settings by opening MirrorSync and pressing Export for each configuration. This will save each configuration's settings in a simple text file.<br />
# Next, you may uninstall MirrorSync off the server. This will clear the license information and prevent users from syncing to the old server. <br />
# After moving the FileMaker file to the new server, install MirrorSync at the new location and enter your license information. You can them Import your configurations back in.<br />
<br />
'''Please note!''' After moving servers, changing your server's hostname, or IP address, you will need to edit the data sources in the FileMaker file. To do this, open the file on the server and choose File> Manage > External Data Sources and clear out any MirrorSync data sources. Walk through the configurations in MirrorSync again, and repaste the script steps, which will create new data sources with the information provided during setup. Distribute new copies of this correct file to all users, as older versions will not sync.<br />
<br />
You will only need to do this if you need to change the addresses you provided MirrorSync previously. For example, if you made a configuration that pointed to MacMini.local, and never provided an IP address, then there's no reason to walk through this process every time the IP address changed. However, if you specified the internal and external IP addresses in MirrorSync, and those change, this process would be required.<br />
<br />
===Configuration questions===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: I tried to follow the configuration utility, but don't quite understand the process. Do you have a walkthrough somewhere?|I tried to follow the configuration utility, but don't quite understand the process. Do you have a walkthrough somewhere?]]<br><br />
[[#Q: How do I configure synchronization for solutions with multiple database files?|How do I configure synchronization for solutions with multiple database files?]]<br><br />
[[#Q: What happens if I edit my configuration, or make changes to the sync layouts on my hosted database?|What happens if I edit my configuration, or make changes to the sync layouts on my hosted database?]]<br><br />
[[#Q: I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?|I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?]]<br><br />
[[#Q: My external IP addresses are different than my internal IP addresses. What do I need to do?|My external IP addresses are different than my internal IP addresses. What do I need to do?]]<br><br />
[[#Q: Is FileMaker Pro Advanced completely necessary for configuration?|Is FileMaker Pro Advanced completely necessary for configuration?]]<br><br />
[[#Q: I never saw the foreign key mapping screen! What do I do?|I never saw the foreign key mapping screen! What do I do?]]<br><br />
[[#Q: I'm not seeing my databases from the Choose database button. What's happening?|I'm not seeing my databases from the Choose database button. What's happening?]]<br><br />
[[#Q: I keep getting a 102 Field is missing error, but I know my Sync layouts have all the right fields, what's wrong with it?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: I tried to follow the configuration utility, but don't quite understand the process. Do you have a walkthrough somewhere?====<br />
A: There is a [[MirrorSync configuration walkthrough]] page that explains this in more detail.<br />
<br />
====Q: How do I configure synchronization for solutions with multiple database files?====<br />
A: MirrorSync will work fine with multi-file solutions. Whether you're using the separation model, migrated from an older version of FileMaker, or just prefer to split our your tables into separate files, we've got you covered. You will need to select one file as your main file. Make sure that the main file contains table occurrences from the other database files that you want to sync, and when the configuration screen instructs you to create layouts for each table, be sure to create the layouts in the main file.<br />
<br />
When you complete the setup process and get to the step where you click the button to download an offline copy of the database from your server, select the option for a multi-file solution. This will show a checkboxes of all of the database files available on the server. Be sure to select all the database files in your solution.<br />
<br />
====Q: What happens if I edit my configuration, or make changes to the sync layouts on my hosted database?====<br />
A: If you change your configuration or edit your hosted database in a way that affects the sync layouts, then your need to go back through and edit the configuration and re-generate the sync script steps. Delete the current contents of the MirrorSync script and replace with the steps you just downloaded. Then send a copy of this new file to each offline user to replace their database.<br />
<br />
====Q: I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?====<br />
A: After converting your file, you'll need to edit the configuration and replace the MirrorSync script steps with ones generated for the FileMaker 12 file. This is due to the fact that the "Insert from URL" script step doesn't exist in FileMaker Pro 11.<br />
<br />
You'll also need to re-run the MirrorSync installer.<br />
<br />
====Q: Is FileMaker Pro Advanced completely necessary for configuration?====<br />
A: If you do not have a license for FileMaker Pro Advanced, you'll need to import the table data from the XML schema that came with your MirrorSync download.<br />
<br />
Please see [[#Configuring_MirrorSync_without_FileMaker_Pro_Advanced|Configuring MirrorSync without FMP Advanced]] for detailed instructions.<br />
<br />
====Q: I never saw the foreign key mapping screen! What do I do?====<br />
A: If you selected UUIDs as your primary keys at the beginning of the configuration, the foreign key screens will not appear. This is normal and expected behavior. When using serial numbers, primary keys can be (and usually are) re-numbered when they are transferred to another device. MirrorSync needs to know which foreign keys which point to the primary keys, in order to write the new primary key value to each foreign key. When using UUIDs, the primary keys stay the same on every device because there is no possibility of conflict. Therefore, there is never a need to re-write foreign keys.<br />
<br />
====Q: I'm not seeing my databases from the Choose database button. What's happening?====<br />
A: Make sure XML publishing is enabled for the account you are using in MirrorSync. Also be sure the database is accessible from the machine you are installing MirrorSync on.<br />
<br />
Try to navigate to your server's URL, and adding <code>/fmi/xml/FMPXMLRESULT.xml?-dbnames</code> to the end. You should see an XML document listing the databases in FileMaker Server. If you do not, or find a 404 or 401 error, then FileMaker Server may not be configured correctly.<br />
<br />
If there is an authentication required at that test URL, try disabling IIS authentication. FileMaker Server authenticates its password-protected databases; however, this method disables the IIS authentication layer. This will also disable authentication for other websites that are using IIS on that server.<br />
<br />
# From the Control panel, navigate to Administrative Tools > Internet Information Services (IIS) Manager<br />
# Select the website in IIS and choose Action > Properties<br />
# Navigate to the Directory Security pane, and select Edit for authentications. This button may differ in various Windows versions.<br />
# In the Authentications Methods pop up:<br />
#* Make sure Anonymous Access is enabled<br />
#* For Authenticated access, disable the authentication methods.<br />
# Press OK<br />
<br />
====Q: I keep getting a 102 Field is missing error, but I know my Sync layouts have all the right fields, what's wrong with it?====<br />
Please make sure that the sync layouts are matching in both the offline and server copy. If you have repeating fields, make sure the fields show the maximum number of repetitions that are defined in the field definitions. In other words, if a field can repeat 5 times, make sure the repetitions in the inspector show 5. <br />
<br />
<br />
===Sync questions===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: Why can't I transfer my database to another computer after I've synced it?|Q: Why can't I transfer my database to another computer after I've synced it?]]<br><br />
[[#Q: Can I log into my local copy with different accounts/different privilege sets?|Q: Can I log into my local copy with different accounts/different privilege sets?]]<br><br />
[[#Q: Does MirrorSync sync container fields?|Q: Does MirrorSync sync container fields?]]<br><br />
[[#Q: What about SuperContainer? Does MirrorSync work with that?|Q: What about SuperContainer? Does MirrorSync work with that?]]<br><br />
[[#Q: Does MirrorSync sync external container fields?|Q: Does MirrorSync sync external container fields?]]<br><br />
[[#Q: Does MirrorSync do conflict resolution?|Q: Does MirrorSync do conflict resolution?]]<br><br />
[[#Q: Is MirrorSync transactional? What happens if the connection is lost while syncing?|Q: Is MirrorSync transactional? What happens if the connection is lost while syncing?]]<br><br />
[[#Q: Can I use external authentication with MirrorSync?|Q: Can I use external authentication with MirrorSync?]]<br><br />
[[#Q: How do I make changes to my hosted database if I have offline users who are syncing? Can I add fields and tables?|Q: How do I make changes to my hosted database if I have offline users who are syncing? Can I add fields and tables?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: Why can't I transfer my database to another computer after I've synced it?====<br />
A: The MirrorSync server stores information about each device that syncs with it. This includes the primary key, as well as the count of modifications for that record on that particular device. If this file were to be synced from two different devices, this information would conflict and cause problems. If you do try to send a database to another device and sync it, an error message will appear and the sync will be prevented.<br />
<br />
====Q: Can I log into my local copy with different accounts/different privilege sets?====<br />
A: No, you'll need to download a new copy of the database for each of the user accounts you use to the server using multiple accounts with the same file may generate errors.<br />
<br />
====Q: Does MirrorSync sync container fields?====<br />
A:Yes, MirrorSync works with FileMaker container fields as of version 1.1. If container fields are slowing down your synchronization, consider moving containers to a separate table and create new layouts for them. MirrorSync scans for modification timestamps to find records that have been changed, so by moving containers to a separate table with a separate timestamp, they are only uploaded and downloaded when containers change. <br />
<br />
====Q: What about SuperContainer? Does MirrorSync work with that?====<br />
A: Yes, it does. However, with SuperContainer the approach is very different. Only the URLs are synchronized, not the actual files - they remain on the SuperContainer server. The advantage is syncing is very fast - there is no binary data being transferred. The disadvantage is that you'll only have access to the files stored in SuperContainer when you have working network access from your computer or iOS device.<br />
<br />
====Q: Does MirrorSync sync external container fields?====<br />
A: Yes, MirrorSync works with external container fields. If you are using external container fields in FileMaker 12, there are a few steps after configuration that are required.<br />
<br />
#Download a copy of the database from MirrorSync or FileMaker Admin<br />
#Open the copy on a computer, and navigate to File > Save a copy as...<br />
#Under the type drop down, choose "self-contained copy (single file)<br />
<br />
This ensures the copy of the file embeds the containers into the file for easy use with FileMaker Go and offline functionality. <br />
<br />
PLEASE NOTE: there is an unexpected behavior in FIleMaker in this process: when saving the self-contained copy, FileMaker updates the modification timestamp for every record that has an external stored container field. That's not a problem normally, but when used with MirrorSync, it will make the initial sync very slow. The reason behind the slow initial is due to MirrorSync assuming that all of those records have been modified on the client, so it writes all of the server data to the client (including the container data). <br />
<br />
The workaround for this is to uncheck the modification timestamp auto-entry before saving the self-contained copy, and then turn it back on after the copy has been saved. This modification timestamp behavior has been reported to FileMaker, Inc. and will hopefully be resolved soon.<br />
<br />
====Q: Does MirrorSync do conflict resolution?====<br />
A:MirrorSync 1.2 introduced a choice of manual conflict resolution or automatic conflict resolution. If a user syncs their changes and a conflict arises, the user has an option of selecting either. Selecting manual conflict resolution will bring up an interface that highlights differences in the server and client copies. For each conflict, users can select which version of the record will win and MirrorSync will use that record. MirrorSync does not 'merge' changes - it will always pick one entire record as the winner of the conflict.<br />
<br />
Previous versions of MirrorSync, and automatic conflict resolution keep track of which change was made last, and selects that as the winner in a conflict. So if a record is changed at 2PM on one device, and 3PM on another device, the 3PM change will win the conflict. The exception is that changes always win over deletions, regardless of which one happened last. A common misconception is that conflict resolution is based on who syncs first or last - MirrorSync will pick the record that was EDITED last, not the one that was SYNCED last. Again, MirrorSync does not 'merge' changes - it will always pick one entire record as the winner of the conflict.<br />
<br />
====Q: Is MirrorSync transactional? What happens if the connection is lost while syncing?====<br />
A: MirrorSync is not 'transactional' in the strictest sense. If the connection is dropped during a sync, it is possible for records from one table to be written to the server, while records from another related table may not be written. However, MirrorSync keeps track of which records have been written and which ones have not, and it will resume from where it was on the next sync and complete everything as if the first sync had finished. If a record on the server cannot be written because it is being edited, the offline user will get a warning error message telling them this. MirrorSync will continue to retry that edit operation each time the sync script is run.<br />
<br />
====Q: Can I use external authentication with MirrorSync?====<br />
A: Yes, MirrorSync supports externally authenticated accounts with no modifications. So long as the username on the local copy matches the username on the server, you can set up one password for local access and another for external authentication with the server. The passwords do not need to match between the local file and the hosted file.<br />
<br />
====Q: How do I make changes to my hosted database if I have offline users who are syncing? Can I add fields and tables?====<br />
A: MirrorSync will match your fields by name whenever you sync. What this means is that as long as you don't rename or delete fields, you can freely add additional tables and fields to your hosted database without causing problems for your users working with the older databases running offline. Don't forget to add new fields to your sync layouts. To distribute your updated version of the database to users, re-run the configuration process and select any new fields and tables to add to the sync configuration. Be sure to re-copy your script steps for the MirrorSync script. Then download a copy of the database from the server and send it to your users to get them the newest version. Users running the old version will be able to sync until they are ready to download the newest version of the file.<br />
<br />
===Primary key / serial numbers===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: What is the difference between serial numbers and UUIDs? Which one should I pick?|What is the difference between serial numbers and UUIDs? Which one should I pick?]]<br><br />
[[#Q: I'm running FileMaker 12, and my primary keys are UUIDs. When I try to sync I get errors. What's going on?|I'm running FileMaker 12, and my primary keys are UUIDs. When I try to sync I get errors. What's going on?]]<br><br />
[[#Q: Do I need to change how my primary keys are generated?|Do I need to change how my primary keys are generated?]]<br><br />
[[#Q: After a couple of syncs I noticed that the serial numbers on my records don't match on my iPad and my laptop. Is this a problem?|After a couple of syncs I noticed that the serial numbers on my records don't match on my iPad and my laptop. Is this a problem?]]<br><br />
[[#Q: What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?|What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?]]<br><br />
[[#Q: Does the sync run any faster if you use UUIDs rather than serial numbers?|Does the sync run any faster if you use UUIDs rather than serial numbers?]]<br><br />
[[#Q: How do I configure and use two foreign keys as a primary key?|How do I configure and use two foreign keys as a primary key?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: What is the difference between serial numbers and UUIDs? Which one should I pick? ====<br />
When you pick 'serial numbers', MirrorSync does not write primary keys from one database to another - it lets each database generate its own primary keys, in a normal sequential order. This means that when record #4 on an iPad, for example, gets written to the server, it might get stored there with primary key #8, for example. MirrorSync records these two ID numbers and maintains its own internal map between the two. In the future, when changes are made to record #4 on the iPad, MirrorSync knows that it should make the changes to record #8 on the server, not #4. This means that you don't have to worry whether your primary keys for newly created records conflicts with the same primary key for different records on other devices. In addition, MirrorSync will re-write foreign keys, so that if any records related to record #4 on the iPad, MirrorSync will will store #8 in their foreign key field when it writes them to the server.<br />
<br />
When you pick 'UUID', MirrorSync will write the primary key unmodified to the other database. It is your responsibility to make sure that the same primary key is never created on multiple devices, otherwise there will be a conflict between two different records with the same primary key. There are many ways to accomplish this; MirrorSync does not know or care how you do it. Some examples are:<br />
* Using an auto-entered UUID for the primary key<br />
* Using simple serial numbers, but assigning different numeric ranges to different devices (ie. Tom creates records starting from 100,000, while Bob creates records starting from 200,000)<br />
* Prepending the user's initials or some other unique identifier to the primary key value<br />
* Using even numbers on one device and odd numbers on another (modify as necessary for more than two devices)<br />
* Getting the next serial number from some network source<br />
* Only allowing one database in the sync to create new records<br />
* Etc...<br />
<br />
In our testing, there is not a substantial benefit to one approach or the other. UUIDs are better if you ever need to merge databases without using MirrorSync. Serial numbers take less space and transmit across the network more quickly. We recommend using whichever approach you feel most comfortable with.<br />
<br />
====Q: I'm running FileMaker 12, and my primary keys are UUIDs. When I try to sync I get errors. What's going on?====<br />
A: Make sure that if you are using UUIDs as primary keys, the "Prohibit Modification of these Values" box is unchecked in the specify field window. MirrorSync must be able to write to these fields.<br />
<br />
====Q: Do I need to change how my primary keys are generated?====<br />
A: No. MirrorSync does not require primary keys to be unique across devices. If you pick the 'serial numbers' option, It will take care of keeping track of primary and foreign keys that are re-numbered when they are transferred to other devices.<br />
<br />
====Q: After a couple of syncs I noticed that the serial numbers on my records don't match on my iPad and my laptop. Is this a problem?====<br />
A: No, serial numbers are expected to be different between devices, because when a record is written from a mobile device to the server, another record may already exist with that same serial number. MirrorSync keeps track of which serial numbers are assigned to which records. For example, if the contact record 'Jesse Barnum' is ID #1 on your laptop, and the same record is #8 on the server, and the same record is #4 on your iPad, Then when a change to record #1 is written from your laptop to the server, MirrorSync knows to make the change to record #8. When you download the change on your iPad, MirrorSync knows to change record #4 on the iPad. It also updates all foreign keys that link to the primary key (this is why the foreign key mapping step is important in the setup process).<br />
<br />
====Q: What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?====<br />
As the previous FAQ points out, if you are using serial numbers for your primary keys, MirrorSync will renumber these serial numbers when it writes to another device to prevent number conflicts. However, this can be a problem for things like invoice numbers, that need to always be the same for all devices. This isn't really MirrorSync's "fault", because obviously if the devices are off-line from each other, there is no way to know what the next available serial number is if it might have been used by another off-line device.<br />
<br />
Before talking about solutions to this problem, it's important to emphasize that this user-friendly number should NOT be what you use as a primary key in your database. Primary keys are internal database identifiers, and should not do double-duty as a user-readable value, so even if you are not using MirrorSync, you should have two fields in your table: One hidden field used as a primary key that the user never sees, and then a second user-visible serial number that users can refer to. With that in mind, here are two potential solutions to the problem:<br />
<br />
1) Have a separate database file that is hosted on the server (not off-line) with a table that contains serial numbers. When you want to generate the next serial number, go to that online table, create a new record, and use that next serial number for your invoice number (or whatever user-visible field this is). Since this database is online, everybody shares it and nobody gets the same serial number. The downside of this is that you won't be able to create new records unless you have a network connection to the server, but the upside is that you can still get all of the speed benefits of working on your own offline copy of the database (since only the serial number table is hosted on the server).<br />
<br />
2) Either use a prefix for each device (so that records created on machine 'ABC' would be numbered ABC1, ABC2, ABC3, while records created on machine 'DEF' would be numbered DEF1, DEF2, DEF3), or assign a serial number range to each device (so records created on 'ABC' would be numbered 10,001, 10,002, 10,003, and records from DEF would be numbered 20,001, 20,002, 20,003). The downside to this approach is that your user-visible number will be longer, and also that you need to customize the database slightly for each device (either by changing the next serial number or by setting the prefix).<br />
<br />
If you'd like our assistance doing the integration and development for this, we'd be happy to help - please contact us for an estimate.<br />
<br />
====Q: Does the sync run any faster if you use UUIDs rather than serial numbers?====<br />
A: The choice of primary keys do not substantially affect the speed of processing data in MirrorSync. Serial numbers are somewhat more network efficient.<br />
<br />
==== Q: How do I configure and use two foreign keys as a primary key? ====<br />
A: In the configuration screen, use the drop down menus to select the two foreign keys. <br />
<br />
Please keep in mind primary keys need to be unique. If using two foreign keys, there may be an instance where an error occurs about a duplicate node ID, since FileMaker is not validating the fields together and making sure they are always unique in a table. To avoid this, make sure:<br />
<br />
#Ensure that the combination of two foreign keys only ever occurs once in the database.<br />
#If you need to be able to have multiple join table records with the same foreign keys, add a regular serial number field to the join table and use that as the primary key, instead of the compound foreign keys.<br />
<br />
===Performance questions===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: How fast is MirrorSync?|How fast is MirrorSync?]]<br><br />
[[#Q: How well does MirrorSync perform on slow networks?|How well does MirrorSync perform on slow networks?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: How fast is MirrorSync?====<br />
A: From a speed standpoint, there are three types of operations that MirrorSync does: 1) Initial sync, 2) syncing inserts and edits, and 3) syncing deletions. #1 and #3 are affected by the number of records in your database, but #2 is not.<br />
<br />
For each sync, there is an overhead associated with sync that is typically 1/4 - 1/2 of a second per table on a local network. Therefore, if you sync 20 tables, expect about 5 or 10 seconds in addition to the actual time to sync the records. For iOS devices, this is more like 2-3 seconds per table.<br />
<br />
For syncing inserts and edits, we find that 20 records per second going from server to client is a fairly typical benchmark. Therefore, if 100 records have been edited on the server, it should take about 5 seconds to sync these records to the client. This number will be higher or lower depending on how much information is stored in your records, and is more like 4 or 5 records per second for iOS devices.<br />
<br />
Syncing inserts and edits from the client to the server is about 5 records per second for FileMaker Server 11, and 40 records per second for FileMaker Server 12.<br />
<br />
Detecting deletions takes about 1 second per 1,000 records in your table. This can be time consuming if you have a large number of records. See the performance tips section below for tips on improving this.<br />
<br />
Initial sync takes about the twice as long as deletion - 2 seconds per 1,000 records in the table. This only happens the first time that a user syncs with an offline copy of the database.<br />
<br />
====Q: How well does MirrorSync perform on slow networks?====<br />
A: MirrorSync is very efficient over slow networks, because it sends very little data other than the actual record changes, and it transmits this information in large chunks, which is more efficient. There are 2 HTTP request at the beginning of the sync, and usually 2 HTTP requests per table that contains any modifications. For example, if you have a 20 table solution, and there are only changes in 5 of the tables, it will usually take 12 HTTP requests (2 + 2*5) to complete the sync. By comparison, the FileMaker home page takes 65 HTTP requests to load in a web browser.<br />
<br />
===Customizing MirrorSync===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?|I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?]]<br><br />
[[#Q: How does MirrorSync work with restricted accounts?|How does MirrorSync works with restricted accounts?]]<br><br />
[[#Q: I don't want users to have to click on the dialog that comes up at the end of the sync, can I hide that?|I don't want users to have to click on the dialog that comes up at the end of the sync, can I hide that?]]<br><br />
[[#Q: Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?|Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?]]<br><br />
[[#Q: Can MirrorSync run automatically every x seconds/minutes?|Can MirrorSync run automatically every x seconds/minutes?]]<br><br />
[[#Q: I have users in different time zones. Does MirrorSync account for that?|I have users in different time zones. Does MirrorSync account for that?]]<br><br />
[[#Q: My file is very large, and I want to give MirrorSync more memory allocation. How do I give Tomcat more memory?|My file is very large, and I want to give MirrorSync more memory allocation. How do I give Tomcat more memory?]]<br><br />
[[#Q: I want to sync very large containers and data. How can I increase the timeout limits?|I want to sync very large containers and data. How can I increase the timeout limits?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?====<br />
A: That's a three-part question with a three-part answer. Just syncing certain tables is very easy: When you're configuring the sync using the MirrorSync configuration utility, only include layouts corresponding to the tables that you want to sync.<br />
<br />
Syncing certain fields is also very easy: Just don't include any fields on your sync layouts except the ones that you want to sync. You can also simply uncheck unwanted fields in the MirrorSync configuration utility.<br />
<br />
Syncing certain records is only slightly less easy: Utilize the record level access privileges in FileMaker's security management dialog to create custom restrictions. For example, you can easily restrict each user to only see their own records by creating a calculated restriction that checks to see if Get(AccountName) is equal to a field with an Account Name auto-entry option. With a little creativity, you can set up similar restrictions to only sync records with certain statuses, or which fall in certain date ranges.<br />
<br />
If you decide to use this technique to limit records based on access level privileges, you may choose to distribute an empty clone to your users instead of a full copy of the database. That way, the initial sync will only pull the records into their offline file that they have access privileges to on the database. Keep in mind that if they have access to many thousands of records, that could make the initial sync slower than if you distributed a full copy of the database that already contains all of the record data.<br />
<br />
====Q: How does MirrorSync work with restricted accounts?====<br />
<br />
MirrorSync requires a full access account only once: to paste in the table, scripts, and layout. After configuration, feel free to distribute copies of your file to restricted users. When MirrorSync does a sync, it logs in to the server copy as the user doing a sync, and won't be able to sync changes they don't have access to. See the above question for distributing empty clones, but please note the question above is more a guide on how to create these restricted accounts, and this question deals more with currently existing accounts. <br />
<br />
'''<big>WARNING</big>''': If you use a start up script that sets global variables which then determine access privileges, these privileges will not get set. The Web Publishing Engine in FileMaker does not run start up scripts, and so these globals won't be set when MirrorSync tries to write changes. A way to set up custom access instead would be to use the Get(AccountName), Get (AccountPrivilegeSetName) functions to determine access levels. This could avoid the start up script entirely.<br />
<br />
====Q: I don't want users to have to click on the dialog that comes up at the end of the sync, can I hide that?====<br />
A: Yes, set the global variable $$SILENT_MODE to "1" in your startup script. This will prevent MirrorSync from showing a dialog unless an error occurs.<br />
<br />
====Q: Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?====<br />
A: Yes, absolutely. Remember that the MirrorSync script is a regular FileMaker script that can be set to run at any time by the developer. For example, if there is a critical section of your application that you want to avoid conflicts, trigger the sync when the user navigates to that screen, and again when they are finished editing in that screen. You could make it so that checking a box, clicking a button, or any other condition that you choose can trigger the sync to happen. If you'd like to incorporate MirrorSync into your startup script, but you only want it to run the first time that user opens an offline file, you can switch to the MirrorSync table and do a search for any record that has a value in the 'lastClientToken' field. If there is at least one record matching the search, then this file has been synced before.<br />
<br />
====Q: Can MirrorSync run automatically every x seconds/minutes?====<br />
A: Yes, you can use an On Timer script to trigger this. However, keep in mind that when the script runs, it commits the current record and pops open a new window that could be open for a few seconds or longer. This could get annoying if it happens in the middle of something that the user is working on. For this reason, we recommend the approach in the previous FAQ entry of linking your script sync operations to some user-initiated action. The exception to this is unattended computers - if you want to have a computer that is running MirrorSync all the time for purposes of having an extra copy of the database replicated, without a user working on it, then by all means go ahead and use an On Timer script step (and be sure to see the FAQ above about disabling dialogs).<br />
<br />
====Q: I have users in different time zones. Does MirrorSync account for that?====<br />
A: Yes. When an offline client syncs with the server, one of the first pieces of information it sends to the client is the client's current time. The server compares this to its own clock to see how different the client is (whether from being in a different time zone or just the client's clock being wrong), and then it applies this offset amount to all the timestamps it receives from the client for writing modification timestamps and resolving conflicts.<br />
<br />
For online users connecting directly to the server, this offset cannot be calculated. Therefore, it is possible that online users in a different time zone, or whose clock is incorrect by more than 10 minutes (MirrorSync automatically includes a 10 minute "overlap"), could have their modifications missed by the sync process. To solve this problem, we recommend adding a new field, called something like 'Host modification timestamp', in addition to a regular modification timestamp field. Set the field type to 'Timestamp', and configure this auto-entered calculation:<br />
<br />
<pre><br />
Let( x=Modification timestamp; Get ( CurrentHostTimeStamp ) ) //Change modification timestamp to be whatever the name of your modification timestamp field is<br />
</pre><br />
<br />
<b>Be SURE to uncheck the box titled 'Do not replace existing value of field (if any)'.</b><br />
<br />
Repeat this step for every table. This Host modification timestamp should now be configured as the modification timestamp for MirrorSync.<br />
<br />
====Q: My file is very large, and I want to give MirrorSync more memory allocation. How do I give Tomcat more memory?====<br />
A: For some users, they may find that the default memory allocation is insufficient to transmit large amounts of data. To allocate more memory to Tomcat, modify the catalina.bat (for Win) or catalina.sh (for Mac) file in the Tomcat directory. To find that directory: <br />
<br />
:For FileMaker 11:<br />
:FileMaker Server/Web Publishing/publishing-engine/cwpe-tomcat/bin/<br />
:For FileMaker 12:<br />
:FileMaker Server/Web Publishing/publishing-engine/jwpc-tomcat/bin/<br />
<br />
Open the catalina.bat (for Win) or catalina.sh (for Mac), and find the following lines:<br />
<br />
<pre><br />
# FileMaker Server CWPE Tomcat Settings<br />
CATALINA_HOME="../../../../Common/Tomcat"<br />
CATALINA_BASE=".."<br />
JAVA_OPTS="-server -d32 -Xmx512M -DFMS.COMPONENT=cwpe -Dcom.prosc.devmode=true"<br />
</pre><br />
<br />
You can then change the -Xmx512M parameter to -Xmx1024M, which will double the memory available.<br />
<br />
====Q: I want to sync very large containers and data. How can I increase the timeout limits?====<br />
<br />
A: As of MirrorSync 1.4301, you can configure MirrorSync to override the default timeout values. To do so, you must find and modify the MirrorSync configuration XML file:<br />
<br />
Library/360Works/Applications/conf/Catalina/localhost/MirrorSync.xml '''OR''' <br><br />
Program Files/360Works/Applications/conf/Catalina/localhost/MirrorSync.xml <br />
<br />
Open this file with a text editor, and find the lines below. You can then modify these values to your own specifications. <br />
<pre><br />
<Parameter name="clientSecondsPerInsertion" value="1.5" /> <!--2 records every 3 seconds for non-container inserts--><br />
<Parameter name="clientSecondsPerContainerInsertion" value="15" /> <!--1 record every 15 seconds if we're inserting containers--><br />
<Parameter name="clientSecondsPerUpdate" value="5" /> <!--1 record every 5 seconds for normal updates--><br />
<Parameter name="clientSecondsPerContainerUpdate" value="15" /> <!--1 record every 15 seconds for updating containers--><br />
<Parameter name="clientSecondsPerDeletion" value="1" /> <!--1 record per second for deletions--><br />
<Parameter name="clientSecondsPerFetchRecord" value=".1" /> <!--10 records per seconds for getting changes records from client--><br />
<Parameter name="clientSecondsPerContainerFetchRecord" value="10" /> <!--1 record per 10 seconds for getting records from client that have one or more container fields--><br />
<Parameter name="clientSecondsPerFetchHeader" value=".03" /> <!--33 headers per seconds for just fetching primary key and modification timestamp (no record data)--><br />
</pre><br />
<br />
=== Licensing ===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: Is MirrorSync included in the 360Works Portfolio Bundle?|Is MirrorSync included in the 360Works Portfolio Bundle?]]<br /><br />
[[#Q: From a licensing standpoint, what is a 'solution'?|From a licensing standpoint, what is a 'solution'?]]<br /><br />
[[#Q: Is there an unlimited device license for MirrorSync? What about for vertical market solutions?|Is there an unlimited device license for MirrorSync? What about for vertical market solutions?]]<br /><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: Is MirrorSync included in the 360Works Portfolio Bundle?====<br />
A: Yes, the Portfolio Bundle (http://360works.com/portfolio) includes MirrorSync. This is the same license as if it were purchased separately - up to 10 devices and 2 FileMaker solutions.<br />
<br />
====Q: From a licensing standpoint, what is a 'solution'?====<br />
A: From a business standpoint, a solution is one or more FileMaker database files that are integrated together for the purpose of meeting a particular business need. From a technical standpoint, there must be a single FileMaker file that contains external table occurrences in its relationship graph pointing to tables stored in other FileMaker data files. To be considered a single solution for purposes of MirrorSync licensing, a file must satisfy both the business and technical requirement.<br />
<br />
====Q: Is there an unlimited device license for MirrorSync? What about for vertical market solutions?====<br />
A: No, we do not offer an unlimited device license for MirrorSync. The same applies for vertical market solutions. For vertical market applications, we recommend that you pre-integrate your solution with MirrorSync, using the demo version of MirrorSync. Then tell your customers that if they would like to enable the offline sync feature, they can purchase MirrorSync separately, with no development work required. All that is needed is to install the MirrorSync software on their server, enter the license key using the admin utility, and customize the FileMaker sync script with the IP address of their MirrorSync server (this can be stored in a settings table, so that it doesn't have to be customized for each client / device).<br />
<br />
=== Miscellaneous questions ===<br />
<br />
====Q: Is MirrorSync localized into any non-English languages? Does it work in other languages?====<br />
A: At this time, MirrorSync is only localized to English. Our current focus is on adding features, but we anticipate translating this into other languages when the product is more mature. If you would like to offer help with translation, please contact plugins@360works.com to let us know. You should still be able to add MirrorSync to your solution in other languages, although we have discovered that copying and pasting the script steps does not work with other languages active - you must switch to English for this step of the configuration, and then you can switch back. Do so by editing your preferences in FileMaker Pro and selecting English in Windows, or by opening System Preferences in Mac, choosing English, and restarting FMP.<br />
<br />
====Q: I only have an offline copy of my file left, and need to upload it back to the server. What do I do?====<br />
A: Please note that this is an unsupported use of the offline file. But if necessary, users can reupload an offline copy of the file to FileMaker Server and use it with MirrorSync. Users will need to remove the "Client" record in the MirrorSync table, and keep only the "Server" record. Navigate to the MirrorSync layout, open the Debugging tab, and perform a find for "Server" in the type field. Select the inverse of the records found by pressing the pie icon in the status bar. Then, delete those other records.<br />
<br />
==Performance / speed optimization tips==<br />
'''Limit fields on the sync layout'''<br /><br />
It's a good idea to remove unnecessary fields on your sync layouts. Unstored calculations, summary fields, and related fields can cause significant slowdowns and are not synced anyway, so they should definitely be removed from the layout. Global fields and stored calculations do not affect speed as much, but they are not used for sync either so it's best to remove them if speed is important.<br />
<br />
'''Move container fields into their own separate table'''<br /><br />
When MirrorSync checks if a record has been modified, it looks at the modification timestamp. If a record has been changed, it downloads the entire record, including container fields, every time. By moving container fields off the regular sync layouts, MirrorSync will only download and upload containers when they have actually changed. To implement this optimization, create a new table that is used only to store the container fields. Put your containers fields in that table, and add a primary key and modification timestamp. Be sure to import all the actual container data from the old table to the new one. Then, take the containers off your current sync layouts (if you have already configured MirrorSync), and create a new layout for the container table. Be sure to re-run the MirrorSync configuration utility so that it knows about the new layout.<br />
<br />
'''Create layouts with just the ID and the modification timestamp'''<br /><br />
FileMaker 11 transmits data differently than FileMaker 12 to MirrorSync. This technique doesn't have any effect with FileMaker 12, but it may make the initial synchronization as well as deletion scanning much faster for FileMaker 11 tables with more than 1,000 records. For each Sync layout, create a new layout with the suffix _small. For example, you may have a table called Contacts. When you set up MirrorSync, you'd make SyncContacts. Now create another layout called SyncContacts_small. On this layout, place the primary key and modification timestamp ONLY. MirrorSync will automatically detect this layout and quickly scan for modification timestamps and records to add and delete. There is no need to rerun the configuration utility or script steps with this option. <br />
<br />
'''Flag records instead of deleting them'''<br /><br />
If you want to optimize performance here, it might make more sense to flag records as being deleted instead of actually deleting them. That makes it into an edit operation, which is not affected by the number of records in the table.<br />
<br />
== Troubleshooting/Known Issues ==<br />
<br />
=== The maximum number of users are currently using this copy of FileMaker Pro===<br />
<br />
[[File:MirrorSyncLicense.png|thumb|Example of error message]]<br />
<br />
There is a small bug in FileMaker Pro and FileMaker Pro Advanced that may occur when pasting the MirrorSync script, or editing the MirrorSync script. This occurs due to the references found in the script, which will reference both the internal and external IP address. FileMaker then opens both those references, which triggers the licensing server as two copies of FileMaker Pro. This error would occur for any script that contains both references to a single hosted file. <br />
<br />
There are three work arounds for this:<br />
<br />
# Upgrade your single user license to a volume license. You can contact FileMaker directly to upgrade your license if you have 5 or more copies.<br />
# Change your Data Sources to list the internal address first in both MirrorSync scripts. You should have either the data sources listing one IP each, or two data sources with two IP addresses. Either way, make sure that both have the internal address listed first, and then for the External source list the external IP in a second line. This will only call the internal IP references when opening the script, but will '''slow down syncs significantly.''' It will now try the internal IP address first, and if it unavailable, time out and then try the external address.<br />
# Paste the script and let FileMaker crash. The script will save appropriately. You will not need to modify the script after the initial configuration, so it should work correctly. If an update is released that requires changes to the script, be aware that any sync buttons or references to the MirrorSync script will have to be corrected on updates. <br />
<br />
If you require assistance on this issue, please let us know.<br />
<br />
=== The operation couldn’t be completed. (OSStatus error -67049.) === <br />
<br />
Apple's new Mountain Lion feature, Gatekeeper, prevents software from being installed outside the Mac App Store. However, you should be able to override Gatekeeper settings with right or control click. This way of getting around Gatekeeper does not always work correctly, and may result in the error message, "The operation couldn't be completed. (OSStatus error -67049)" To continue with MirrorSync or any other non App Store application, disable Gatekeeper completely in your System Preferences, perform the installation, and reenable once finished.<br />
<br />
As of MirrorSync 1.5, the installer has been completely rewritten and no longer encounters the issues with Gatekeeper's right or control click. <br />
<br />
=== Error from server: java.lang.IllegalArgumentException: Invalid date value (XXXXXXXXX) ===<br />
<br />
This error occurs when invalid timestamps are being used in timestamp fields. This could be due to legacy timestamps that were previously stored in text fields and then converted to timestamp fields. FileMaker will retain the preexisting data in the field, but will not allow new invalid data to be entered.<br />
<br />
The solution to this problem is to convert the existing invalid timestamps to equivalent timestamps in the correct format (MM/DD/YYYY HH:MM:SS). For example, if the contents of your timestamp fields appear like this YYYY-MM-DD HH:MM:SS you would isolate the found set of all records with invalid timestamps, and perform a Replace Field Contents operation with this code as the calculated result:<br />
::Let ( [<br />
<br />
::var.ts = Table::TimestampField ;<br />
::var.year = Left ( var.ts ; 4 ) ;<br />
::var.month = Middle ( var.ts ; 6 ; 2 ) ;<br />
::var.day = Middle ( var.ts ; 9 ; 2 ) ;<br />
::var.date = Date ( var.month ; var.day ; var.year ) ;<br />
::var.time = Trim ( Middle ( var.ts ; 11 ; 100 ) )<br />
<br />
::];<br />
<br />
::Timestamp ( var.date ; GetAsTime ( var.time ) )<br />
<br />
::)<br />
<br />
This code only works for invalid timestamps in one specific format (YYYY-MM-DD HH:MM:SS), but with only slight modification, it could be made to work with many different invalid timestamp formats.<br />
<br />
=== Manual Installation of MirrorSync 1.5===<br />
<br />
Users who have updated to FileMaker Server 13 or who need a more customized solution may need to perform a manual installation of the MirrorSync software. MirrorSync runs on your server as an Apache Tomcat application; therefore, it will run alongside the Web Publishing engine using the existing Tomcat instance installed by FileMaker Server or you can download and install the Apache Tomcat server application for your operating system to run MirrorSync in a standalone Tomcat Server (this may involve setting Tomcat up to start automatically with your system, as well as configuring your web server to forward traffic for MirrorSync to port 80). <br />
<br />
The default configuration for MirrorSync is to install in the FileMaker Server Web Publishing Engine. This is the easiest installation method to configure, and is easily redirected to port 80. Alternatively, you may install MirrorSync in a standalone Tomcat server of your choice. This option is available if you do not want to modify the Web Publishing Engine or if you need further customization.<br />
<br />
====Installing in the FileMaker Server Web Publishing Engine====<br />
=====Prerequisites=====<br />
* Be sure FileMaker Server is installed and running with XML Custom Web Publishing enabled.<br />
<br />
=====Installing MirrorSync=====<br />
* Copy the MirrorSync.war file from the Installer Data folder into the jwpc-tomcat folder located at <code>FileMaker Server/Web Publishing/publishing-engine/jwpc-tomcat/</code> (a MirrorSync folder will be created automatically when the .war file is dropped in place).<br />
* Now you should be able to access the MirrorSync sync admin splash page by visiting <code>http://localhost:16020/MirrorSync</code> verify that you are able to successfully access this page.<br />
* (FMS13) Back in the jwpc-tomcat folder, navigate to <code>jwpc-tomcat/MirrorSync/META-INF/</code> and edit the context.xml<br />
* (FMS12) Back in the jwpc-tomcat folder, navigate to <code>jwpc-tomcat/conf/Catalina/localhost/</code> and edit the MirrorSync.xml<br />
** Specify your username and password on these two lines of the <code>MirrorSync.xml/context.xml</code> file:<br />
*** <code><Parameter name="adminUsername" value=""/></code><br />
*** <code><Parameter name="adminPassword" value="" /></code><br />
<br />
=====URL Redirection=====<br />
NOTE: These instructions apply only to users installing inside the FMS13 Web Publishing Engine.<br />
======Windows======<br />
FileMaker Server 13 uses the URL Rewrite module of IIS to redirect traffic from the native HTTP Tomcat port 16020 to the standard web traffic port 80<br />
<br />
* Launch the IIS Manager, expand the Sites folder, then click on the FMWebSite site. You will see a collection of modules in the center pane of IIS Manager.<br />
* Double click the module that reads <code>URL Rewrite.</code><br />
* In the right hand pane, click <code>Add Rule(s)</code> at the very top of the list of actions.<br />
* From here, choose <code>Blank rule</code> and press OK<br />
* Set up the rule to match the pattern for the requested URL using regular expressions. <br />
* Set the pattern as <code>^MirrorSync(.*)</code><br />
* Scroll down to the action section and be sure the action type is set to <code>Rewrite</code><br />
* Set the Rewrite URL as <code>http://localhost:16020/MirrorSync{R:1}</code><br />
* Be sure <code>Append query string</code> and <code>Stop processing of subsequent rules</code> are both checked, then apply the settings and test the the MirrorSync URL in your browser (http://localhost/MirrorSync)<br />
<br />
======Mac======<br />
FileMaker Server 13 uses ProxyPass redirection to redirect traffic from the native HTTP Tomcat port 16020 to the standard web traffic port 80<br />
<br />
* Navigate to <code>FileMaker Server/Admin/admin-helper/WEB-INF/conf/</code> and open the <code>mod_proxy.conf</code> file with a text editor. You will need elevated permissions to modify this file.<br />
* Add these lines to the end of the <code>mod_proxy.conf</code> file:<br />
** <code>ProxyPass /MirrorSync ajp://127.0.0.1:16021/MirrorSync</code><br />
** <code>ProxyPassReverse /MirrorSync ajp://127.0.0.1:16021/MirrorSync</code><br />
* Save the file back to its original location.<br />
<br />
Now Apache needs to be restarted, but we need to be sure to restart Apache with the FMS13 configuration.<br />
* Open a terminal window and enter <code>cd "/Library/FileMaker Server/HTTPServer/bin"</code> and press return.<br />
* Enter this command to restart Apache (you will need to enter your system password when prompted): <code>sudo ./httpdctl graceful</code><br />
* Test the MirrorSync URL in your browser (http://localhost/MirrorSync)<br />
<br />
====Alternative - Installing in a standalone Apache Tomcat Server====<br />
=====Prerequisites=====<br />
* Download and install Apache Tomcat 6.x or 7.x from http://tomcat.apache.org, for Windows make sure to download the installer<br />
* Follow Tomcat documentation for running Tomcat as server, for Windows make to make the service selection during installation<br />
* Start up Tomcat (this usually happens automatically when using the installer, otherwise you will need to run the Catalina shell script with a 'start' command).<br />
<br />
=====Installing MirrorSync=====<br />
* Copy the MirrorSync.war file from the Installer Data folder into the <code>$TOMCAT_HOME/webapps</code> folder in your Tomcat instance.<br />
* (Tomcat 6) Modify the <code>MirrorSync.xml</code> file located in the <code>$TOMCAT_HOME/conf/Catalina/localhost/</code> folder.<br />
* (Tomcat 7) Modify the <code>context.xml</code> file located in the <code>$TOMCAT_HOME/webapps/MirrorSync/META-INF/</code> folder.<br />
** Specify your username and password on these two lines of the <code>MirrorSync.xml</code> file:<br />
*** <code><Parameter name="adminUsername" value="" /></code><br />
*** <code><Parameter name="adminPassword" value="" /></code><br />
* If necessary for your configuration, set up URL forwarding from IIS / Apache to your Tomcat connectors. See Tomcat documentation on how to do this.<br />
<br />
== More Help Sources ==<br />
<br />
If you still need help, there are several resources available! [http://fmforums.com/forum/forum/172-mirrorsync-by-360works/ FMForums] hosts a support forum for MirrorSync. Please look through the posts and see if your question has been posted before making a new topic.<br />
<br />
Support is also available via email at plugins@360works.com. You can also call us at 770-234-9293. <br />
<br />
We're confident you'll be able to configure MirrorSync quickly and easily. However, if you want to have us integrate MirrorSync your solution for you, it will take approximately an hour at our rate of $165. We'll take a look at your files first, and if the integration will take more than an hour we'll contact you. Contact us to learn more and get started!<br />
<br />
== Troubleshooting ==<br />
<pre><br />
http://server/fmi/xml/FMPXMLRESULT.xml?-dbnames<br />
http://server/fmi/xml/FMPXMLRESULT.xml?-db=<yourDb>&-lay=MirrorSync&-findany<br />
</pre></div>Sarahhttp://docs.360works.com/index.php/MirrorSync_advanced_topicsMirrorSync advanced topics2014-01-27T17:11:59Z<p>Sarah: Added FAQ for links not doing anything with iOS 7</p>
<hr />
<div>Welcome to the advanced section of the MirrorSync documentation! This guide will help you customize MirrorSync to suit your development needs, and provide detailed instructions for various situations. If you would like a good general overview of the software, please read through [[MirrorSync basic setup]] first!<br />
=== Deployment questions===<br />
<br />
====How do I uninstall MirrorSync?====<br />
To uninstall on Mac, run the 'Mac Uninstaller.pkg' that comes with the MirrorSync. On Windows, run 'C:\Program Files\360Works\Uninstall.<br />
<br />
====Installation for hosting providers====<br />
To install multiple instances of MirrorSync, choose the Hosting provider option in the installer. This is exactly the same as the regular installation process, except that it will allow you to rename the instance of MirrorSync. You can continue running the installer as many times as you like, once per client, renaming each instance to something unique. These copies can then be managed via the 360Admin utility, which is found either in your Program Files or Applications folder. When installing additional instances of the application, only a single Tomcat process will be installed which is shared by all of the MirrorSync instances.<br />
<br />
We recommend you use the installer. We at 360Works use the installer for our hosting clients as well, and find it easy to update and manage. If you are curious as to what the installer actually does, it modifies and adds the following:<br />
<br />
* Creates a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows that is readable and writeable.<br />
* Downloads and installs an instance of [http://tomcat.apache.org/download-60.cgi Tomcat 6] into that folder. (Only one copy of Tomcat is installed, regardless of how many copies of MirrorSync are running)<br />
* Copies and renames the installer's MirrorSync.war, which deploys the web app, as well as the other supporting material into the folder.<br />
* Adds a launch daemon in Library/LaunchDaemons in OS X, or creates a Windows Service to automatically start Tomcat.<br />
* Modifies the http.conf file for Apache to allow for URL redirection. If using Windows with IIS, we create an ISAPI filter or a URL Rewrite rule for the URL redirect.<br />
* Copies a lightweight Admin Utility JAR file to manage Tomcat to either C:\Program Files\360Works or /Applications.<br />
<br />
If upgrading from an older version of MirrorSync, we'll copy over the SyncData and remove the URL redirects for the old MirrorSync.<br />
<br />
If you prefer MirrorSync to be deployed to your own instance of Tomcat that you've set up, please note and follow these instructions:<br />
<br />
# Create a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows. Make sure that it is readable and writeable to the process that Tomcat is running as. This is where MirrorSync stores its private data including the internal sync database and the stored configurations. If you have a strong preference for locating this someplace else, because of disk space for example, set the '360directory' system property to point to some other path.<br />
# Rename the MirrorSync.war file to whatever name you'd like the instance to run as for your hosting customer, ie. 'CustomerXSync.war' If you decide to run multiple instances of MirrorSync with the same name (using multiple instances of Tomcat), you'll need to set '360directory' separately for each Tomcat instance, otherwise those multiple instances will overwrite each other's private data.<br />
# Drop that .war file into the webapps directory in your Tomcat instance.<br />
# Modify the the MirrorSync.xml context descriptor and set the administrative username and password for MirrorSync. In Tomcat 6, this file is automatically written to the Tomcat/conf/Catalina/localhost. If you are running Tomcat 7, the file is located in the webapps/MirrorSync/META-INF/context.xml file, or you can follow the instructions at http://tomcat.apache.org/tomcat-7.0-doc/config/host.html regarding copyXML to get the same behavior as Tomcat 6 (we recommend doing this, so that you don't lose the context.xml file every time the application is redeployed).<br />
# If necessary for your configuration, set up URL forwarding from IIS / Apache to your Tomcat connectors. [http://tomcat.apache.org/tomcat-6.0-doc/index.html See tomcat documentation on how to do this].<br />
<br />
==== Installing without a network connection ====<br />
The MirrorSync installer normally needs a network connection during the installation process. It uses this to download a copy of Apache Tomcat 6 from the Apache web site, as well as doing a network license check to validate the license key. If you are in an environment that has no outbound network capabilities, you can still install MirrorSync, but you'll need to follow these extra steps:<br />
<br />
# Contact support@360works.com and ask for a customized build of MirrorSync that does not need a network connection for license checking. Be sure to include your license key and registration information.<br />
# Manually create a new folder at /Library/360Works (on Mac) or C:\Program Files\360Works (on Windows).<br />
# Download Apache 6 from http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.36/bin/apache-tomcat-6.0.36.zip and place it into the 360Works directory.<br />
<br />
Now you should be able to run the installer without any network connection.<br />
<br />
==== Split server deployments ====<br />
If your FileMaker deployment is split onto multiple machines, we recommend installing MirrorSync on the FileMaker Server machine. This allows the download database feature in MirrorSync to work, which greatly simplifies deployment to end users. If you will not use the download database feature, and you do not plan on sending download URLs to your users, then install MirrorSync on the web server, for maximum speed during syncing.<br />
<br />
Regardless of which computer you install on, be sure that when you are configuring MirrorSync, you specify that the MirrorSync / FM Server machines are on different computers. This option is on the first screen in the new configuration process.<br />
<br />
====Does MirrorSync work with runtime versions of FileMaker Pro?====<br />
MirrorSync is untested and unsupported for use in this configuration. In addition, the legal licensing agreement for creating runtime versions of FileMaker specifically disallows any automated transfer of data between the runtime version and FileMaker Server. This restriction means that no sync process can legally be used to transfer data between the runtime edition and FileMaker Server, whether that is from a 3rd party or a home-grown automation process. Contact your FileMaker Business Account Manager for volume pricing on FileMaker Pro licenses.<br />
<br />
====What if I need to redeploy FileMaker Server?====<br />
If using a Mac, no additional steps should be required. However, if you are running Windows, you'll want to rerun the installer for MirrorSync.<br />
<br />
<div id="upgradeFrom1"></div><br />
====I am running MirrorSync 1. What do I need to do to upgrade to 2?====<br />
Any extra configurations or devices you purchased with MirrorSync 1 will carry over to MirrorSync 2 after purchasing the upgrade.<br />
<br />
# First, have all of your offline users run a sync. They will need to replace their offline files with new versions, so this will prevent them from losing any data.<br />
# MirrorSync 2 requires a creation timestamp field, in addition to the modification timestamp. Create that field if you do not already have one, and be sure to add it to all the MirrorSync layouts.<br />
# Run the MirrorSync installer. MirrorSync 1 configurations will not be preserved, so you'll need to create new configurations and distribute new copies of the files to your users. The good news is that since you already have all of your sync layouts ready to go, and also since MirrorSync 2 automatically detects foreign keys (requires FileMaker Server 12 or later), this shouldn't take much time at all.<br />
# Download new copies of the file for your users, and enjoy all the great features and speed of MirrorSync 2!<br />
<br />
=== Networking questions ===<br />
<br />
====Can MirrorSync send encrypted data? What about SSL enabled FMS?====<br />
<br />
Yes, it can. To make sure data is encrypted, you'll need a valid SSL certificate installed on the web server where MirrorSync is running. This will ensure that all plain-text data is sent and received encrypted with SSL. To sync container data using SSL, first set up FileMaker server as SSL enabled ([http://www.filemaker.com/downloads/documentation/fm12_security_guide_en.pdf see page 20 of these docs]). After doing so or if FileMaker Server is already is SSL enabled, check the SSL checkbox when configuring MirrorSync. <br />
<br />
If you get an error saying that you have a self-signed certificate, then you will need to follow the [[Custom SSL Certificate setup instructions]].<br />
<br />
<br />
====I need my database to be HIPPA compliant, what should I do with MirrorSync?====<br />
HIPPA compliance depends on a large number of requirements. However, one of those requirements is to transmit only encrypted data. See the question above if you experience difficulties. Please keep in mind that encryption is one piece of HIPPA compliance, so consult the [http://www.hhs.gov/ocr/privacy/ Department of Health and Human Services] for more information.<br />
<br />
<br />
====What ports are required for MirrorSync? Can I change them?====<br />
MirrorSync transmits container data on port 5003, which is the regular port for communication betwen FileMaker Pro and FileMaker Server. All other field types (text, number, date, time, timestamp) are transmitted using regular HTTP communication, which typically runs on port 80, or port 443 if SSL encryption is being used. These port numbers are set in your web server configuration (IIS on Windows or Apache on OS X), and can be customized to any value you prefer. A good way to test this is to test the FileMaker Web Publishing Engine - if the URL 'http://yourServer:somePort/fmi/xml/FMPXMLRESULT.xml?-dbnames' returns an XML list of database names, then it should work for MirrorSync as well.<br />
<br />
====Will MirrorSync work on a VPN?====<br />
Yes. MirrorSync runs over standard HTTP protocols (which are VPN compatible) for non-container data, and standard FileMaker protocols (which are also VPN compatible) for container data.<br />
<br />
====My solution is behind a firewall. Will MirrorSync still work?====<br />
MirrorSync communicates with FileMaker Server using a web viewer, so as long as the firewall allows standard HTTP traffic on port 80 (almost all firewalls are configured to allow this), all of your sync devices should be able to access it through the firewall. The exception to this is container fields. If you are syncing container fields, you will need to make sure that port 5003 (FileMaker's standard port) is open on the firewall, because the client needs to connect as a guest of the server to transfer container data.<br />
<br />
<div id="nat"></div><br />
<br />
==== Is MirrorSync compatible with Network Address Translation (NAT)? ====<br />
Yes. When configuring MirrorSync, select the option that says 'My internal and external IP addresses are different.' This will write the sync script so that if it detects it's running on the same LAN as MirrorSync, it will use the internal IP address, and if it's running outside the MirrorSync LAN, it will automatically switch to the external IP address.<br />
<br />
<br />
<br />
<br />
===Primary key / serial numbers===<br />
<br />
====What is the difference between 'MirrorSync-managed' and 'Developer-managed' primary keys? Do I need to change how I do my primary keys? Which one should I pick? ====<br />
Before answering this question, it's first necessary to explain why primary keys are a complex issue with synchronization. With traditional incrementing serial numbers, one database might have records numbered 1 through 10. Another database might have records 1 through 50. If we create a new record on the first database, it will get assigned the next number in the sequence (11). However, if we try to write that record to the second database, it will conflict with record 11 that already exists there. Here are several approaches to solving that problem:<br />
# '''Use Universally Unique Identifiers (UUIDs) as primary keys'''. These are typically long, 36-character strings that look like this: "D2EF9F69-5DEA-4FE3-9095-162C77F76FBF". They are sufficiently random to statistically eliminate the possibility of duplicate values. This makes them ideally for syncing databases - you can safely write records from one database to another without worrying about conflicting IDs. MirrorSync (and most other sync frameworks) supports UUIDs.<br />
# '''Combine a traditional serial number with some delimiter''', such as each user's initials or a file ID. This way, user 1 would have primary keys "1.1", "1.2", "1.3", and so on. User 2 would create primary keys "2.1", "2.2", "2.3", etc. This has the advantage of being shorter and more readable than UUIDs, but the added management consideration of assigning unique identifiers to each user. MirrorSync can manage this for you, as explained later.<br />
# A variation on the second solution would be to '''assign each user a particular numeric range''', so that user 1 generates primary keys in the range of 1-10,000; user 2 generates primary keys 10,001-20,000; and so on. This has the advantage of pure numeric values (instead of text), but the disadvantage of the possibility of conflicts if a user exceeds the expected number of records. MirrorSync can manage this approach as well.<br />
# A very different approach is to '''allow conflicting primary keys to exist on each separate database, without ever writing those primary keys to other databases'''. When record #11 is written from the first database to the second (in our original example), instead of being written with primary key 11, it is written with primary 51 (the next number in the sequence on the second database). This has the advantage of the shortest possible primary keys, which are pure numeric values, with no possibility of conflicts. It is also the way that the majority of existing databases are designed. MirrorSync supports this method (and is the only sync framework that does, to our knowledge). It creates an internal table to translate between the primary keys on all database that are syncing, so that when record #11 is later updated, MirrorSync knows to change record #51 in the second database. MirrorSync also re-writes foreign keys when they are written from one database to another, so that foreign keys that contained '11' on the first database will be re-written with '51' in the second database.<br />
<br />
Options 1, 2, and 3 are considered ''''Developer-managed'''', because MirrorSync writes the primary keys unmodified between the databases being synced. It is the developer's responsibility to pick some scheme that ensures that the same primary key is never used for different records on different databases. There are other variations on the same theme (ie. one database gets odd numbers and the other gets even numbers), but they all are treated the same by MirrorSync.<br />
<br />
Option 4 is considered ''''MirrorSync-managed'''.' The developer is not responsible for the uniqueness of primary keys across different databases; MirrorSync takes care of this for you.<br />
<br />
As to which you should pick, the answer is usually this: If your FileMaker database is currently using UUIDs, use developer-managed. If your database is written using traditional serial numbers, you should use MirrorSync-managed. However, if you need 'user-friendly' numbers for things like invoice numbers, job numbers, or check numbers, [[#writebacks|read the next FAQ]] on user-friendly serial numbers before making a decision.<br />
<br />
If you are building a new database and can use whichever approach you want, here are the relative advantages:<br />
* Serial numbers are more efficient because they are smaller. [[#What can I do to speed up syncing?|See the performance section of this documentation]] for more discussion on this.<br />
* UUIDs are easier to use if you need to ever sync or import manually without using MirrorSync, or switch to some other sync tool (which only support UUIDs).<br />
<br />
<div id="writebacks"></div><br />
<br />
====What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?====<br />
The problem with MirrorSync-managed serial numbers is that they are not suitable for user-visible numbers, such as invoice numbers. That's because the primary key will be different on one device than another. If you're using the primary key serial number as your invoice number, it is clearly a problem if your invoice number is different between your laptop and the server!<br />
<br />
There are several solutions to this problem. One of the first things to establish is whether your database uses a single field as both the primary key and the user-visible value (we'll refer to it as the 'invoice number'). It is always preferable (even when not syncing) to have these be separate fields from each other. Invoice numbers / job numbers / user visible numbers should NOT be what you use as a primary key in your database. Primary keys are internal database identifiers, and should not do double-duty as a user-readable value.<br />
<br />
If the fields are separate, the problem becomes simpler to solve, because you have the flexibility to change the value of the invoice number without breaking relationships. See the section below on write-back values for the recommended approach.<br />
<br />
If the same field is being used for the primary key and the invoice number, and if it is feasible to split this into two separate fields (one for relationships, and one for display/searching), you should do so. Unfortunately, this can sometimes be a very big job - creating the new field is easy, but then you either need to find every place that that field is used in the user interface and point it to the newly created invoice number field, or else you need to find every place that it is used in the relationship graph and re-point that to the newly created primary key field. If you do not want to do this, then see the section below on MIRRORSYNC_CLIENTID for the recommended approach.<br />
<br />
{{mbox <br />
| type = warning<br />
| text = <b>One mistake you should be careful to avoid is this:</b> If your database is currently designed with serial numbers for primary keys, do not try to short-cut the solution by simply creating a new UUID field and try to trick MirrorSync into using that as your primary key. MirrorSync won't re-number your foreign keys, which means that the wrong children records will point to the wrong parent records when the records are synced with the server.}}<br />
<br />
===== Write-back values for user-visible numbers =====<br />
Let's say that you have a UUID as your primary key field, as well as an invoice number field. Using the write-back approach, the invoice number field will be blank when a record is created in an offline file. When that invoice record is synced to the server, it will get assigned the next invoice number, and that number will be written back to the invoice number field on the offline file. This approach does not work unless the invoice number field is separate from the primary key.<br />
<br />
Advantages of this approach:<br />
* Invoice numbers are in a simple, short numeric sequence, just like they would be without syncing.<br />
<br />
Disadvantages:<br />
* The offline file does not get an invoice number until the record is synced for the first time.<br />
<br />
To use this approach, follow these steps:<br />
* If you do not already have a serial number field in your table, create one. If you have a serial number which is used as a primary key, that's usable. We'll call that field 'serialNumber' in our example.<br />
* Define your invoiceNumber field this way: <code>If( Get( MultiUserState ) = 2; serialNumber; "" )</code>. This will leave the invoice number blank when working offline, but fill it in when connected directly to the server.<br />
* In the primary key selection screen in MirrorSync, select invoiceNumber as the write-back field. This will cause MirrorSync to write invoiceNumber from the server back to the offline file when the record is first synced.<br />
* Your choice of MirrorSync-managed or Developer-managed is unaffected by this setting; pick appropriately depending on whether you are using serial numbers or UUIDs as your primary key.<br />
<br />
===== MIRRORSYNC_CLIENTID for user-visible numbers =====<br />
Let's say that you have a single serial number as your primary key, which is doing double-duty as an invoice number field. You can use the $$MIRRORSYNC_CLIENTID global variable to help. Using this approach, MirrorSync ensures that each file being synced gets assigned a unique sequential number, starting from 1. You can use this number in conjunction with a traditional serial number to create a unique number than can be used as a user-visible field as well as a primary key. The serial numbers will either be text (ie. "1.1", "1.2", "1.3"…) or numeric (10,001 for user 1, 20,001 for user 2, 30,001 for user 3…).<br />
<br />
Advantages of this approach:<br />
* Reasonably short user-visible numbers<br />
* IDs are assigned immediately upon record creation, without needing to wait for syncing<br />
<br />
Disadvantages:<br />
* Offline users must do an initial sync before they can create records.<br />
* Requires a startup script to run, which means it won't work with custom web publishing applications.<br />
* IDs are not sequential, so you can't assume that an ID with a higher value was created before or after another ID.<br />
* If you are using numeric version, limits users to creating a fixed number of records before they start conflicting.<br />
* If you are using text version, you must switch all primary key and foreign fields from 'number' type to 'text.'<br />
* Setup is a bit more complex than write-back fields.<br />
<br />
To use this approach, follow these steps:<br />
* Set the 'MirrorSync setup' script as your startup script. If you already have a startup script, call the 'MirrorSync setup' script from your existing script. This will set the $$MIRRORSYNC_CLIENTID global variable. This clientId field is stored in the MirrorSync table, and is assigned when the user does their first sync. Each synced database will get a unique, sequential clientId. Manually run the script now to set that global variable before proceeding.<br />
* We assume you have a serial field called 'serialField'. Start off by duplicating this field, to create a new field called 'serialField copy.'<br />
* Change serialField to an auto-enter calc. Uncheck the box that says 'Do not replace existing value'. Also make sure that the 'Prohibit modification of value during data entry' is unchecked. Set the formula to one of the following:<br />
For text keys, use this formula. This will result in primary keys that look like "1.1", "1.2", "1.3" from device 1, and "2.1", "2.2", "2.3" from device 2. Feel free to modify as desired. Be sure to change the field type from number to text. Also change all foreign keys that relate to it to text.<br />
<pre><br />
$$MIRRORSYNC_CLIENTID & "." & serialField copy<br />
</pre><br />
for numeric keys, use this formula. This will result in primary keys that look like "10001", "10002", "10003" from device 1, and "20001", "20002", "20003" from device 2. Replace whatever number you want instead of 10,000 to give a wider or narrower range of numbers.<br />
<pre><br />
$$MIRRORSYNC_CLIENTID * 10000 + serialField copy<br />
</pre><br />
* For primary key configuration in MirrorSync, select Developer-managed, and set 'serialField copy' as your primary key.<br />
<br />
<br />
<div id="compoundkey"></div><br />
<br />
==== How do I configure and use two foreign keys as a primary key? ====<br />
This is a common configuration for join tables in many-to-many relationships. In the primary key configuration screen, use the drop down menus to select the two foreign keys.<br />
<br />
Please keep in mind primary keys need to be unique. If using two foreign keys, there may be an instance where an error occurs about a duplicate node ID, since FileMaker is not validating the fields together and making sure they are always unique in a table. To avoid this, make sure:<br />
<br />
#Ensure that the combination of two foreign keys only ever occurs once in the database.<br />
#If you need to be able to have multiple join table records with the same foreign keys, add a regular serial number field to the join table and use that as the primary key, instead of the compound foreign keys.<br />
# The foreign key fields must both have the 'Not empty' validation in order to appear in the pull-down menu of eligible fields. If your join table needs to have foreign keys that may be empty, you should add a traditional single primary key to the table instead of using compound foreign keys as an identifier for MirrorSync.<br />
<br />
===Configuration questions===<br />
<div id="differentfile"></div><br />
==== Does MirrorSync need the databases being synced to be identical? ====<br />
No, not in MirrorSync 2. MirrorSync is able to sync between databases with completely different tables and fields from each other. In addition, it can sync just a subset of records, fields, and tables. If you are syncing different databases, for example a dedicated mobile file with a much larger server database, select the option 'Sync with a separate mobile file' (for FileMaker Go) or 'Sync with a separate server file' (for server-to-server sync). With this option selected, MirrorSync will allow you to match up your layout and field names with a simple drag and drop interface.<br />
<br />
====Why does MirrorSync need to know about foreign keys?====<br />
MirrorSync uses foreign keys for two purposes. If you are using MirrorSync-managed primary keys, then it needs to know about the foreign keys because it needs to rewrite them when it writes between databases (see the primary key section above).<br />
<br />
In addition, even if you're using developer-managed primary keys, MirrorSync needs to know about relationships so that it can sync parent tables before children tables. This allows validation rules that check referential integrity to work correctly.<br />
<br />
MirrorSync 2 adds a new feature that automatically detects foreign keys, if you are using FileMaker 12 or later, so this step should not add any time to the configuration process. If you are using FileMaker 11 AND you are using developer-managed primary keys AND if you do not have any referential integrity validation making sure that foreign keys point to valid parent records, you can safely skip this step.<br />
<br />
====I'm not seeing my databases from the Choose database button. What's happening?====<br />
Make sure XML publishing is enabled for the account you are using in MirrorSync. Also be sure the database is accessible from the machine you are installing MirrorSync on.<br />
<br />
To test the XML Web Publishing Engine, try going to the URL <code>http://yourServer/fmi/xml/FMPXMLRESULT.xml?-dbnames</code>. You should see an XML document listing the databases in FileMaker Server. If you do not, or find a 404 or 401 error, then the XML Web Publishing Engine may not be configured correctly. Contact FileMaker tech support for help getting this running.<br />
<br />
If there is an authentication required at that test URL, try disabling IIS authentication. FileMaker Server authenticates its password-protected databases; however, this method disables the IIS authentication layer. This will also disable authentication for other websites that are using IIS on that server.<br />
<br />
# From the Control panel, navigate to Administrative Tools > Internet Information Services (IIS) Manager<br />
# Select the website in IIS and choose Action > Properties<br />
# Navigate to the Directory Security pane, and select Edit for authentications. This button may differ in various Windows versions.<br />
# In the Authentications Methods pop up:<br />
#* Make sure Anonymous Access is enabled<br />
#* For Authenticated access, disable the authentication methods.<br />
# Press OK<br />
<br />
<br />
==== Configuration without FileMaker Pro Advanced ====<br />
<br />
Since FileMaker Pro does not have the ability to copy and paste tables, you'll need to follow these instructions to create the MirrorSync table.<br />
<br />
*Locate the XML schema that came with your MirrorSync download.<br />
*Open FileMaker Pro and navigate to File -> Import Records -> XML Data Source.<br />
*In the "Specify XML and XSL Options" window, choose the "File" radio button, then click "Specify...".<br />
*Navigate to your MirrorSync download folder and choose the MirrorSync.xml file from the XML Schema subfolder.<br />
*Click continue to bring up the Import Field Mapping window. <br />
*Open the "Target" drop down menu, and select "New Table ("MirrorSync")"<br />
*Verify that the source fields and target fields have been matched correctly.<br />
*Click import.<br />
<br />
After the table is created, you'll need to modify some of the fields:<br />
*Navigate to File -> Manage -> Database...<br />
*Navigate to the "Fields" tab, highlight the '''id''' field and click the "Options..." button.<br />
*Check the box next to "Serial Number." Set it to generate on creation.<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the boxes next to "Not Empty" and "Unique Value" then press OK.<br />
*Next, highlight the '''modstamp''' field and click the "Options..." button.<br />
*Check the box next to "Modification" and ensure that the drop down menu says "Timestamp (Date and Time)."<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the box next to "Not Empty" then press OK<br />
*Next, highlight the '''lastErrorMessage''' field and click the "Options..." button.<br />
*Navigate to the "Storage" tab and check the box next to global storage and press OK.<br />
*Repeat the last two steps to make '''webServerResponse, _gSync1, _gSync2, _gSync3, _gSync4, _gLastInsertTable''', and '''_gLastInsertResult''' all be global fields. <br />
*Finally, highlight the '''container''' field, and select "Container" from the "Type" drop down menu, next to the "Options..." button.<br />
You are now finished manually configuring your MirrorSync table. Click the OK button to close the database management window, and return to the MirrorSync configuration. (Be sure to save your changes!)<br />
<br />
<div id="separation"></div><br />
<br />
====Separation model / multiple file solutions====<br />
MirrorSync will work fine with multi-file solutions. You need to make sure that one of the files in your solution has a reference to every table that you want to sync (for separation model solutions, it is better to use the data file than the UI file, because MirrorSync stores some internal data in a new MirrorSync table that it creates in the file). When configuring MirrorSync, use this file. When using the MirrorSync download feature, be sure to select the multi-file option so that your offline users will receive all of the files for the solution.<br />
<br />
====How do I configure External SQL Source (ESS) tables?====<br />
MirrorSync supports ESS tables, but it's very slow compared to using MirrorSync to simply sync the database from the external SQL database into your FileMaker Server. We do not recommend ESS unless syncing is not an option for some reason.<br />
<br />
If you would like to use ESS tables, there are additional steps. First, configure MirrorSync in its entirety. You should be able to select your ESS tables and files in the configuration utility. After you have pasted the last script step, download a copy of the file as usual. <br />
<br />
At this point, you need to make some modifications for the file to work offline. Open the downloaded copy, and make the following modifications to the local copy ONLY! Do not run the sync yet.<br />
<br />
* First, delete the data source. This is vital to preventing duplicate records and other artifacts of using ESS. Open File > Manage > External Data Sources and delete the OBDC data source.<br />
* Next, open the File > Manage > Database and navigate to the Tables tab. Copy any ESS tables. Then delete them. Make sure NOT to delete the table occurrences. After all the italicized tables are gone, paste the tables back in. This ensures they are local FileMaker files, not references to external data.<br />
* Make sure the primary keys, modification timestamps, and creation timestamps are correct. The primary key needs to be an auto-entered serial number or generated UUID.<br />
* Open the relationships tab in the File > Manage > Database and relink the missing tables.<br />
<br />
You can now distribute this file for synchronization to your users. Make a copy of this file and send it to each user who needs a copy. These copies are then ready for synchronization.<br />
<br />
<br />
====I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?====<br />
After converting your file, you'll need to edit the configuration and replace the MirrorSync script steps with ones generated for the FileMaker 12 file. This is due to the fact that the "Insert from URL" script step doesn't exist in FileMaker Pro 11.<br />
<br />
===Sync questions===<br />
<br />
==== Does MirrorSync work with timezones? ====<br />
Yes and No.<br />
<br />
For offline users who are syncing, Yes. When MirrorSync gets a list of all modifications, it will automatically detect the offline user's timezone and clock drift and compensate for it.<br />
<br />
For server-to-server sync, Yes. MirrorSync can detect FileMaker server's current time and compensate for it, just like it does for offline users.<br />
<br />
For non-syncing users connecting directly to FileMaker Server, No, not automatically. You'll need to perform a small work around to make this work. It gets a little complicated, so an example makes it more clear. Let's say your FileMaker Server is hosted in New York. A user in New York runs a sync at 12:30 PM Eastern Time. 30 minutes later, a user in San Francisco modifies a record on the server at 10 AM Pacific Time (1 PM Eastern Time). Due to the way that FileMaker Server works, that modification timestamp on the server in New York will say 10 AM. It will not be converted to Eastern Time, nor will FileMaker Server store any time zone information for anybody to tell that it was actually representing Pacific time. Essentially, it's just an incorrect value. When the next sync runs, MirrorSync is going to request records modified since the last sync at 12:30 PM, which is going to miss the change made by the San Francisco user, even though it was made since the last sync.<br />
<br />
The solution to this problem is very easy - it actually takes less time to do than it did to read that explanation! Let's say that your table contains a regular modification timestamp called 'Modification timestamp'. Create a new field called 'Host modification timestamp' (or whatever you prefer), and set it to auto-enter this calculated value (substituting your own field name in place of 'Modification timestamp'):<br />
<pre><br />
Let( x=Modification timestamp; Get ( CurrentHostTimeStamp ) )<br />
</pre><br />
<b>Be SURE to uncheck the box titled 'Do not replace existing value of field (if any)'.</b><br />
<br />
<b>Don't forget to add it to your sync layout, and REMOVE the regular modification timestamp from the sync layout!</b><br />
<br />
Use this field as the modification timestamp in the MirrorSync configuration process, instead of the regular modification timestamp.<br />
<br />
This works by using the FileMaker Server clock, instead of the user's clock, for the modification timestamp. Now, when the San Francisco user modifies a record at 10 AM Pacific Time, FileMaker Server will store 1 PM (the server's local time when that change was made) in the Host modification timestamp field, and MirrorSync will work with time zones correctly.<br />
<br />
====Why can't I transfer my database to another computer after I've synced it?====<br />
The MirrorSync server stores information about each device that syncs with it. This includes the primary key, as well as the count of modifications for that record on that particular device. If this file were to be synced from two different devices, this information would conflict and cause problems. If you do try to send a database to another device and sync it, an error message will appear and the sync will be prevented.<br />
<br />
====Can I share a device among multiple users?====<br />
Yes, but…<br />
<br />
If all users on that device log in with the same username, then it's <i>probably</i> OK, as long as you make sure that you are not using record level access privileges on the offline device that would grant different record access to different users.<br />
<br />
If you want each user who shares a device to log in with different usernames, then the solution is to put a separate copy of the file on the device, one for each user. Make sure that each user is only able to login to the file that is assigned to them.<br />
<br />
MirrorSync prevents multiple users with different usernames from sharing the same offline file, because if record level access privileges or script filters were configured differently for each user, that would lead to the sync process incorrectly deleting the wrong records on the server, which would be very bad.<br />
<br />
====Does MirrorSync sync container fields?====<br />
A:Yes, MirrorSync works with FileMaker container fields. Container fields do take longer than other field types to synchronize, so remove them from your sync layouts if you don't need them to be synced.<br />
<br />
<br />
====What about SuperContainer? Does MirrorSync work with that?====<br />
Yes, it does. However, with SuperContainer the approach is very different. Only the URLs are synchronized, not the actual files - they remain on the SuperContainer server. The advantage is syncing is very fast - there is no binary data being transferred. The disadvantage is that you'll only have access to the files stored in SuperContainer when you have working network access from your computer or iOS device.<br />
<br />
====Does MirrorSync sync external container fields?====<br />
Yes, MirrorSync works with external container fields. There are no extra steps to take when syncing with FileMaker Pro or FileMaker Server. If you are using external container fields on an iOS device, there are a few steps after configuration that are required.<br />
<br />
#Download a copy of the database from MirrorSync or FileMaker Admin<br />
#Open the copy on a computer, and navigate to File > Save a copy as...<br />
#Under the type drop down, choose "self-contained copy (single file)"<br />
<br />
This ensures the copy of the file embeds the containers into the file for easy use with FileMaker Go and offline functionality. <br />
<br />
PLEASE NOTE: there is an unfortunate behavior in FileMaker in this process: when saving the self-contained copy, FileMaker updates the modification timestamp for every record that has an external stored container field. That's not a problem normally, but when used with MirrorSync, it will make the initial sync very slow. The reason for this slowdown is due to MirrorSync assuming that all of those records have been modified on the client, so it writes all of the server data to the client (including the container data). <br />
<br />
The workaround for this is to uncheck the modification timestamp auto-entry before saving the self-contained copy, and then turn it back on after the copy has been saved. This modification timestamp behavior has been reported to FileMaker, Inc. and will hopefully be resolved soon.<br />
<br />
<br />
==== Why doesn't iOS 7 show a progress bar when I click the download link? Is anything happening? ====<br />
<br />
When you create a download link to share with users, the user will typically click on the link and be presented with a nice download window as expected. With iOS 6, you got a little progress bar that fills across the tab until the file downloads. Unfortunately, iOS 7 removes this download progress indicator, so it may look like nothing is happening after you click the download link. If this bothers you, we suggest filing a [http://www.apple.com/feedback/ feedback suggestion] with Apple directly. However, MirrorSync is actually doing a few things behind the scenes: once the link is triggered, it saves a copy of the hosted file on FileMaker Server and creates a backup of all the data, even if you have selected a clone. It then downloads the file to your device. This may take some time to create the back up and save a copy of the file depending on the size, but MirrorSync notes how long this takes in the log.<br />
<br />
====Does MirrorSync require users to sync with full access accounts?====<br />
<br />
No. MirrorSync requires a full access account only once: to paste in the table, scripts, and layout. When users run the sync, they will use their own user account privileges, with whatever access that grants them. See the '[[#Customizing MirrorSync|Customizing MirrorSync]]' section below for tips on restricting user accounts.<br />
<br />
====Does MirrorSync do conflict resolution?====<br />
Yes, MirrorSync has robust conflict detection and field-level merging (added in version 2). It will detect when the same record(s) are modified on both database and take action. There are two settings in the configuration client that will control how this works:<br />
<br />
* <b>Merge the changes together</b>: If MirrorSync sees that all of the changes made in the databases were to different fields (ie. firstName on the server and lastName on the client), it will automatically merge the changes together. It will not tell the user that a conflict occurred, it will just write the merged record to both the server and the client. If any changes were made to the same field, it is treated as a conflict and not merged.<br />
* <b>Flag the edit as a conflict</b>: MirrorSync will treat all modifications to the same record as a conflict, regardless of whether they were made to the same fields or different fields.<br />
<br />
If a conflict occurs, then MirrorSync will resolve it based on the next configuration option:<br />
* <b>User picks:</b> MirrorSync will present a web-based interface to the user, summarizing all conflicts and showing them exactly which fields were changed on both databases. It color-codes the actual sections of text that were changed, making it easy for even inexperienced users to make the best choice. The user is able to pick one entire record over another, pick individual fields from each record, and even manually edit the result to combine changes from both records. They also have the option to automatically select the most recent change (see next option).<br />
* <b>Most recent change wins:</b> MirrorSync will pick whichever record was last modified as the winner of the conflict. If Joe changes a record on his iPad at 3:00 PM, Kate changes the same record on her iPhone at 3:30 PM, and Tom changes the record on the server at 4:00 PM, then when Joe or Kate sync their database, Tom's record will be selected as the winner, regardless of when Joe and Kate do their sync.<br />
* <b>Hub always wins</b>: MirrorSync will always pick the value on the hub (typically FileMaker Server) as the conflict winner, regardless of other considerations. This is not generally recommended, because it is essentially first-sync wins behavior: Whoever syncs to the hub first will win conflicts with other offline users who modify the same record and sync. This setting can be useful if changes made by directly connected users should be given priority over offline, syncing users.<br />
* <b>Email administrator</b>: This is very similar to 'User picks', except that instead of the user who is doing the sync deciding, an e-mail is sent to the administrator email address specified in the configuration. The administrator can resolve the conflict using the same web-based user interface described above, after which the user will be able to sync normally.<br />
<br />
====Is MirrorSync transactional? What happens if the connection is lost while syncing?====<br />
MirrorSync is not 'transactional' in the strictest sense. If the connection is dropped during a sync, it is possible for records from one table to be written to the server, while records from another related table may not be written. However, MirrorSync keeps track of which records have been written and which ones have not, and it will resume from where it was on the next sync and complete everything as if the first sync had finished. If a record on the server cannot be written because it is being edited, the offline user will get a warning error message telling them this. MirrorSync will continue to retry that edit operation each time the sync script is run.<br />
<br />
====Can I use external authentication with MirrorSync?====<br />
Yes, MirrorSync supports externally authenticated accounts with no modifications. So long as the username on the local copy matches the username on the server, you can set up one password for local access and another for external authentication with the server. The passwords do not need to match between the local file and the hosted file.<br />
<br />
<br />
<br />
<br />
=== Server-to-server sync ===<br />
<br />
==== How do I set up server-to-server syncing? ====<br />
For the most part, the process for setting up server-to-client sync is almost identical to server-to-server sync. Here are a few differences to be aware of:<br />
* If you will be syncing container fields across a Wide Area Network (WAN), both servers must have public IP addresses, because they each make HTTP calls to the other.<br />
* In the spoke configuration, you select 'copy or clone of existing file' or 'separate file.' If the first option is selected, you don't actually put the file on the other server during the setup process - go through the setup process, and when you're finished, save a copy or clone from the hub server using the MirrorSync download feature and upload it to the spoke server. If you select 'separate file', then you will need to have the file up and running on the spoke server during configuration.<br />
<br />
==== How do I run a server-to-server sync? ====<br />
You do not use the MirrorSync script from within FileMaker, like a server-to-client sync. Instead, use the 'sync' button in the MirrorSync admin utility. Once you've run the sync and are satisfied that everything is working correctly, you may enable auto-sync by checking that box and specifying the frequency to run the sync.<br />
<br />
==== How can I be notified of a problem that occurs during server-to-server sync? ====<br />
There is an administrative e-mail address that is set during MirrorSync configuration. If you set this, you will receive e-mail notifications whenever the sync fails (or succeeds, depending on what granularity you set admin e-mails to). These e-mails are sent via Amazon Web Services, and thus do not require you to configure an SMTP server.<br />
<br />
===Performance questions===<br />
<br />
====How well does MirrorSync perform on slow networks?====<br />
MirrorSync is very efficient over slow networks, because it sends very little data other than the actual record changes, and it transmits this information in large chunks, which is more efficient. There are 3 HTTP request at the beginning of the sync, and usually 2 HTTP requests per table that contains any modifications. For example, if you have a 20 table solution, and there are changes in 5 of the tables, it will usually take 13 HTTP requests (3 + 2*5) to complete the sync. By comparison, the FileMaker home page takes 65 HTTP requests to load in a web browser.<br />
<br />
<br />
====My file is very large, and I want to give MirrorSync more memory allocation. How do I do this?====<br />
MirrorSync has a 512 megabyte allocation by default. This is typically sufficient for syncing change batches of around 200,000 records, although that number gets much smaller if the records contain a lot of information. Now divide that number by the number of devices simultaneously syncing - so if you expect up to 4 people to be syncing simultaneously, MirrorSync can probably handle up to 50,000 changes from each user with the default memory allocation. If you need more than that, you can increase the memory allocation by modifying the setenv file. Find the 512 and change it some new memory allocation, like 1024. The file is at:<br />
<pre><br />
Mac: /Library/360Works/Applications/bin/setenv.sh<br />
Win: C:\Program Files\360Works\Applications\bin\setenv.bat<br />
</pre><br />
<br />
====What can I do to speed up syncing?====<br />
MirrorSync is pretty fast without any special tweaking, but faster is always better. Here are some tips for squeezing out the best possible sync speed from MirrorSync:<br />
<br />
* SSD drives: MirrorSync does many thousands of tiny read and write operations when syncing large record batches. This type of usage will benefit greatly from the ultra-low latency of SSD drives. You will see a noticeable change in sync speed by installing MirrorSync on an SSD drive. You don't need to use an SSD for your entire hard drive - you can just put MirrorSync on the SSD by using a symbolic link in OS X or changing the install location on Windows. The SSD performance benefits will improve all sync operations, but it will be most noticeable when doing very small syncs with few or no changes, and initial syncs for large database with hundreds of thousands of records.<br />
<br />
* When MirrorSync fetches changed records from FileMaker Server, it requests all changes since 10 minutes prior to the last sync. This 10 minute overlap compensates for users whose clocks are slow. If you're using the Host modification timestamp trick outlined in the timezone section above, then the user clock doesn't matter, and you don't need this 10 minute overlap. You can get rid of it by editing the MirrorSync.xml file and change the 'fmServerOverlapSeconds' parameter from 600 (10 minutes) to 5 (5 seconds). The file is at:<br />
<pre><br />
Mac: /Library/360Works/Applications/conf/Catalina/localhost/MirrorSync.xml<br />
Win: C:\Program Files\360Works\Applications\conf\Catalina\localhost\MirrorSync.xml<br />
</pre><br />
<br />
* Use serial numbers instead of UUIDs, especially for large record sets with narrow tables. The difference between a 5 character serial number and a 36 character UUID adds up, especially when transferring large numbers of records that mostly consist of foreign keys, such as join tables. Don't make this change if you have a good reason for using UUIDs.<br />
<br />
* Container fields hold lots of data, require a guest connection to FileMaker Server over port 5003, and are sent individually instead of in batches like non-container data. If there are containers that you don't need to sync, remove them from the sync layouts. Removing all container fields will give much better sync performance, as well as eliminating firewall concerns, because MirrorSync does not need to connect as a guest of FileMaker Server.<br />
<br />
* If you want to just sync a subset of records, instead of the entire database, you can use either record level access privileges or scripted filters (see the customization section below for more details). Scripted filters are much, much faster then record level access privilege restrictions.<br />
<br />
* If you're on FileMaker 11, switch to 12 or later. All of MirrorSync's communication with FileMaker Server is via the XML Web Publishing Engine, and this was just not very fast in FileMaker Server 11. It is greatly improved in later versions of FileMaker Server.<br />
<br />
* Flag records instead of deleting them: MirrorSync 2 is very fast at detecting deleted records. However, it's always faster to sync edits and inserts than to scan for deletions, especially in large tables with more than 100,000 records. If you want to optimize performance, it might make more sense to flag records as being deleted instead of actually deleting them. That makes it into an edit operation, which is not affected by the number of records in the table.<br />
<br />
===Customizing MirrorSync===<br />
<br />
====I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?====<br />
That's a three-part question with a three-part answer. Just <b>syncing certain tables</b> is very easy: When you're configuring the sync using the MirrorSync configuration utility, only include layouts corresponding to the tables that you want to sync.<br />
<br />
<b>Syncing certain fields</b> is also very easy: Just don't include any fields on your sync layouts except the ones that you want to sync.<br />
<br />
<b>Syncing certain records</b> is only slightly less easy: Edit the 'MirrorSync Customization' script and follow the instructions in the 'FindChanges' documentation there to constrain the found set to just the records you want to sync for the current user. Remember that the script will be running as the user doing the sync, so you can use the Get( AccountName ) function to determine which records are available. <b>Be careful regarding the use of $$globalVariables</b> - they will work correctly for the duration of the current sync, but they will not still be set on the next sync (except for $$MIRRORSYNC_USERTOKEN - see next question).<br />
<br />
Any records that are excluded by your search criteria will not be synced to the user. In addition, if those records were previously synced, they will be deleted from the user's device. This makes it very easy to create check-in / check-out workflows with MirrorSync, where jobs are synced to iPads, completed, and then deleted from the device.<br />
<br />
To test your customization script, go to the sync layout that you want to test, show all records, and run the MirrorSync customization script. If you don't get the results you expect, use the Script Debugger to tweak it.<br />
<br />
Another approach to limiting record access is with FileMaker's record level access restrictions. Any restrictions you place on the user's privilege set will be respected by MirrorSync, and the user will only receive those records when they do a sync. Records which were previously visible which switch to non-visible will be deleted on the next sync. Keep in mind that scripted record filters will be much faster than using record level access privileges.<br />
<br />
If you decide to limit the synced records, you may choose to distribute an empty clone to your users instead of a full copy of the database. That way, the initial sync will only pull the records into their offline file that they have access to on the database. Keep in mind that if they have access to many thousands of records, that could make the initial sync slower than if you distributed a full copy of the database that already contains all of the record data, and let the initial sync delete the extra records.<br />
<br />
====How can I filter records on a per-user basis if everybody is logging in with the same Filemaker account?====<br />
Use the $$MIRRORSYNC_USERTOKEN to accomplish this. This is a special global variable that MirrorSync passes from the client to the server when a sync runs. You can set this global variable to whatever you want on the client, and it will be set on the server so that the MirrorSync customization script can use it when searching for records. This global variable is the one exception to the 'no global variables' rule for server-side filtering, so use it any way you want. You'll notice that it is nested in a conditional in the MirrorSync customization script that sets it. That 'If' statement prevents it from being set on the server, which is important because that would override the value sent by the client.<br />
<br />
====How can I tell if a record created in FileMaker Go has been synced with the server?====<br />
During configuration, select any field as a write-back value (see [[#writebacks | write-back values]] in the primary key section, above). Make sure that value is only set to auto-enter a value on the server, by checking that <code>Get(MultiuserState) = 2</code>. If the field is blank, the record has not yet been synchronized. If the field contains a value, then it was either created on the server, or created in FileMaker Go and synced with the server.<br />
<br />
Another approach you can take is by modifying the didInsert section of the customization script (see next question), but the write-back approach is significantly faster when syncing.<br />
<br />
====How can I run a script on the server when a record is synchronized?====<br />
Maybe you want to send an e-mail to an administrator when a user completes a delivery, creates a request for a quote, or deletes a job in production. To do these types of operations, modify the MirrorSync customization script. There is a section in the script for 'DidUpdate', 'DidInsert', and 'WillDelete'. Make sure you modify those in the 'Hub' section - it's very rare that these should be modified on the spoke. In the relevant section of the script, check the current layout, and if it's the one where you want to take action, go ahead and do whatever you want in this section. You can freely go to other layouts, do searches / inserts / updates / deletions, send e-mails, or take any other action, as long as you finish the script on the same layout and record where you started.<br />
<br />
If MirrorSync detects that the record was modified as a result of a 'DidInsert' or 'DidUpdate' script, it will re-do the client search, taking into account any scripted record restrictions in the 'FindChanges' section. For example, if you want jobs to be removed from the user's iPad when a record on the 'SyncJob' layout has its status changed to 'Completed', take these steps:<br />
# Modify the 'FindChanges' to exclude records whose status is 'Completed' when Get(LayoutName) = "SyncJob". (To do this type of search in FileMaker, enter Find mode, Set the status field to 'Completed', Omit the current record/request, and then Constrain Found Set)<br />
# Modify the 'DidInsert' section to blank out the modification timestamp when Get(LayoutName) = "SyncJob".<br />
# Do the same thing in the 'DidUpdate' section.<br />
<br />
Now, whenever an offline user updates or inserts a record in the 'SyncJob' table, the script will blank out the modification timestamp. This triggers a change, which causes MirrorSync to re-do the search, which will exclude the complete job from the search, which will automatically remove it from the iPad.<br />
<br />
You might ask, why blank out the modification timestamp? The answer is that it actually doesn't matter what you do, as long as you make some change to the record at all. Blanking out the modification timestamp is a harmless change, because FileMaker will immediately replace the blank value with a new timestamp. You could just as well set any field on the record to its current value, or make some more meaningful change, such as filling in a date field with the data that the job was completed.<br />
<br />
====I don't want users to see any dialogs when the sync runs, can I prevent them from showing?====<br />
Yes, set the global variable $$SILENT_MODE to "1" in the MirrorSync customization script. This will prevent MirrorSync from showing any dialogs unless an error occurs, and for required information like login and conflict resolution.<br />
* If you would like to also skip the login dialog, AND if you know the user's password (ie. if it's stored in a users table) OR everybody is syncing with the same account, you can hard-code the $$MIRRORSYNC_USERNAME and $$MIRRORSYNC_PASSWORD values in the MirrorSync customization script. If these are both non-empty values, then MirrorSync will not prompt the user to enter their password.<br />
* If you would like to prevent the conflict resolution dialog from displaying, pick any option other than 'user decides' in the conflict resolution section of the MirrorSync configuration process.<br />
<br />
==== I don't want users to see the MirrorSync window at all when a sync runs. Can I prevent that from showing? ====<br />
If you are running MirrorSync on FileMaker Pro, then yes. Set the $$MIRRORSYNC_HIDE_WINDOW variable to 1 in the MirrorSync customization script. This will move the MirrorSync window off-screen, where the user cannot see it. This is not recommended for large sync operations that will take longer than a few seconds, because without that status display, users may think that their computer is frozen.<br />
<br />
If you are running MirrorSync on iOS, then this cannot be hidden. That is because MirrorSync needs to open a new window to manipulate the found set without losing the current selection, and new windows cannot be hidden offscreen on iOS devices. The $$MIRRORSYNC_HIDE_WINDOW variable will be ignored on iOS.<br />
<br />
==== Can I block other MirrorSync dialogs from being displayed to the user, or change the wording? ====<br />
Yes. Using the MirrorSync customization script, all dialogs, even error messages, can be suppressed or modified. Look towards the bottom of the MirrorSync customization script, and you will see a section that includes a dialog for each type of message that is displayed to users during a normal sync. You may freely customize the message displayed to the user, or the title of the buttons (but be sure that the first button still has the same meaning, and the second button still has the same meaning). If you want to hide the dialog from showing, you can disable the script step that displays it, but you must decide which option you would like to select, and exit the script with that button number. You can use this technique to display messages to your users in their preferred language.<br />
<br />
====Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?====<br />
Yes, absolutely. First of all, we recommend setting the 'MirrorSync setup' script as your startup script, or calling it from the startup script. This will check to see if the file is running offline, and whether it has ever been synced before. If not, it will prompt the user to do the initial sync. In addition, the MirrorSync setup script sets the $$MIRRORSYNC_CLIENTID global variable, which is necessary for some primary key strategies ([[#Primary key / serial numbers |see the Primary Key section above]]).<br />
<br />
Remember that the MirrorSync script is a regular FileMaker script that can be set to run at any time by the developer. For example, if there is a critical section of your application that requires users to see what the latest value is before they make a change, trigger the sync when the user navigates to that screen, and again when they are finished editing in that screen. You could make it so that checking a box, clicking a button, or any other condition that you choose can trigger the sync to happen.<br />
<br />
====Can MirrorSync run automatically every x seconds/minutes?====<br />
Yes, you can use an On Timer script to trigger this. However, keep in mind that when the script runs, it commits the current record and pops open a new window that could be open for a few seconds or longer. This could get annoying if it happens in the middle of something that the user is working on. For this reason, we recommend the approach in the previous question of linking your script sync operations to some user-initiated action. The exception to this is unattended computers - if you want to have a computer that is running MirrorSync all the time for purposes of having an extra copy of the database replicated, without a user working on it, then by all means go ahead and use an On Timer script step (and be sure to see [[#I don't want users to see any dialogs when the sync runs, can I prevent them from showing?|the FAQ above about]] disabling dialogs).<br />
<br />
==== Customizing the MirrorSync layout ====<br />
Feel free to make cosmetic changes to the 'MirrorSync' layout that is pasted into your solution. However, follow these tips before making changes:<br />
* Make sure you are able to successfully sync on FileMaker Pro and FileMaker Go before making customizations.<br />
* Make a backup copy of the unmodified MirrorSync layout first.<br />
* It is important that you preserve the tabs on the layout, and that the same fields remain in those tabs. The other thing to be careful about is that there are two 1x1 pixel web viewers on the MirrorSync layout. Make sure that those remain visible on the layout.<br />
* If the sync stops working after you make the changes, then you may have inadvertently lost the web viewers on the layout. Restore them from the backup copy of the layout.<br />
<br />
=== Licensing ===<br />
<br />
==== How does licensing and pricing work for MirrorSync? ====<br />
MirrorSync is completely free to use, with no limitations on features, for syncing FileMaker Server with a single copy of FileMaker Pro or FileMaker Go. You can optionally purchase additional server configurations or devices.<br />
<br />
The supported configuration types are:<br />
* FileMaker Server with FileMaker clients (Go or Pro)<br />
* FileMaker Server with FileMaker Server<br />
* FileMaker Server with any SQL database (Oracle, MySQL, and MS SQL Server are fully supported. You may also sync with any database with a JDBC driver).<br />
* SQL database with SQL database<br />
* SQL database with FileMaker clients (Go or Pro)<br />
<br />
Devices are sold in quantities of 1, 5, 10, 40, and unlimited. These can be purchased in addition to the single device that comes with MirrorSync for free.<br />
<br />
==== Is MirrorSync included in the 360Works Portfolio Bundle?====<br />
Yes. MirrorSync 2 is free for one device, but Portfolio Bundle (http://360works.com/portfolio) subscribers will receive an additional 10 device pack (for a total of 11 devices). Server-to-server configurations are not included in the Portfolio License, and must be purchased separately. There is also a special licensing program for FileMaker Business Alliance (FBA) members; contact us at support@360works.com for details.<br />
<br />
==== Is there a vertical market license type for MirrorSync? ====<br />
Yes. Contact support@360works.com for details about how this works.<br />
<br />
=== Miscellaneous questions ===<br />
<br />
====Is MirrorSync localized into any non-English languages? Does it work in other languages?====<br />
At this time, MirrorSync is only localized to English. Our current focus is on adding features, but we anticipate translating this into other languages when the product is more mature. If you would like to offer help with translation, please contact support@360works.com to let us know. You should still be able to add MirrorSync to your solution in other languages. See the previous section on customizing dialogs for tips on localizing your solution.<br />
<br />
====I only have an offline copy of my file left, and need to upload it back to the server. What do I do?====<br />
If necessary, you can re-upload an offline copy of the file to FileMaker Server and use it with MirrorSync. <b>Be sure to remove the "Client" record in the MirrorSync table</b>, and keep only the "Server" record. To do this, navigate to the MirrorSync layout, switch to the Debugging tab, and perform a find for "Server" in the type field. Select the inverse of the records found by pressing the pie icon in the status bar. Then, delete those other records.<br />
<br />
=== Troubleshooting/Known Issues ===<br />
<br />
==== The maximum number of users are currently using this copy of FileMaker Pro====<br />
<br />
[[File:MirrorSyncLicense.png|thumb|Example of error message]]<br />
<br />
There is a bug in FileMaker Pro and FileMaker Pro Advanced that may occur when pasting the MirrorSync script, or editing the MirrorSync script. This occurs due to the references found in the script, which will reference both the internal and external IP address. FileMaker then opens both of those references, which triggers the licensing server as two copies of FileMaker Pro. This error would occur for any script that contains both references to a single hosted file. <br />
<br />
There are two work arounds for this:<br />
<br />
# Upgrade your single user license to a volume license. You can contact FileMaker directly to upgrade your license if you have 5 or more copies.<br />
# Paste the script and let FileMaker close due the licensing error. The script will save appropriately, and should work correctly.<br />
<br />
If you require assistance on this issue, please let us know.<br />
<br />
====I keep getting a 102 'Field is missing' error, but I know my Sync layouts have all the right fields, what's wrong with it?====<br />
Make sure that the sync layouts are matching in both the offline and server copy. If you have repeating fields, make sure the fields show the maximum number of repetitions that are defined in the field definitions. In other words, if a field can repeat 5 times, make sure the repetitions in the inspector show 5.<br />
<br />
====Sync fails every time with error: Last sync failed: java.sql.SQLException: Error in table <Sync Layout Name>: Parse Error During Update 1: -1====<br />
This issue arises if a syncing solution has more than 998 syncing fields. The limit for the number of variables Filemaker will allow in a Let statement is 1000. During our Server <-> Client transactions, we require two variables for internal use, so the maximum syncing field limit per table is 998.</div>Sarahhttp://docs.360works.com/index.php/First_Data_E4First Data E42014-01-22T15:48:58Z<p>Sarah: Clarified what CCSetTestMode does for the E4 gateway</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==First Data E4==<br />
<br />
First Data E4 can process a wide variety of transactions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account with [https://globalgatewaye4.firstdata.com/ First Data E4], and you'll need to get your Gateway ID and your eCommerce terminal password. Log in to your account, and choose Administration at the top. Navigate to the terminals tab, and click on the eCommerce terminal. You can then view your gateway ID and generate a password. Use these as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of gateway ID and password. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
gatewayID;<br />
password; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. If you have a card present account, pass in cardPresent=true.<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("E4"; "cardPresent=true")]</pre><br />
<br />
'''Returns''': 1 if a valid gateway is provided, ERROR otherwise.<br />
<br />
===Test Mode===<br />
<br />
To run test transactions, call '''CCSetTestMode''' - If set to 1, tells Plastic to perform all subsequent transactions using a demo account, sent to a demo server. You can get a demo account to test with [https://firstdata.zendesk.com/entries/21510561-first-data-global-gateway-e4sm-demo-accounts here]. If '''CCSetTestMode''' is set to 0, that tells Plastic to perform all subsequent transactions as live transactions on the live server with a live account. If this function is never called, the default behavior of Plastic is to treat all transactions as live transactions.<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
Once you properly configure your merchant account, you can quickly and easily process payment transactions.<br />
<br />
You must provide the following information for a credit card payment transaction:<br />
* merchant account name (this might also be known as a store id)<br />
* transaction key (this might also be known as a password or token)<br />
* dollar amount<br />
* credit card number<br />
* credit card expiration date<br />
* card holder's first name<br />
* card holder's last name<br />
<br />
The CCProcessPayment function will process a transaction and return a transaction ID. This function returns a transaction ID if the transaction is successful or the word ERROR if the transaction fails. For detailed information about the most recent transaction failure, call the CCLastError function before calling any other transaction-processing function.<br />
<br />
In your script, you would then have a second line after setting the gateway.<br />
<br />
Set Variable [$result Value: <br />
CCProcessPayment(<br />
gatewayID, <br />
password;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"firstName=" & Payment::First;<br />
"lastName=" & Payment::Last;)]<br />
<br />
'''Returns''': a verification code from the payment gateway service if the order is successful, or "ERROR" if there was a problem<br />
<br />
'''Note''': It is important to store the resulting transaction ID because you may need it later to void the transaction, issue a refund or capture a previously authorized transaction.<br />
<br />
You may submit optional parameters to most of Plastic's payment-transaction processing functions. These parameters will be submitted to the payment gateway along with the basic transaction information. Although they are not usually required to process an order, these parameters can be useful for tasks such as address verification or linking a transaction to a customer id or an invoice number. To supply additional parameters to a function call, add them to the end of the parameter list after the last required parameter, using a "key=value" syntax.<br />
<br />
Set Variable [$result Value:<br />
CCProcessPayment(<br />
gatewayID, <br />
password;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"firstName=" & Payment::First;<br />
"lastName=" & Payment::Last;<br />
"chargeDescription=" & Payment::description;<br />
"verificationCode=" & $securityCode)]<br />
<br />
{{Template:E4 Optional Parameters}}<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
A sale transaction for credit card contains two parts: an authorization which verifies and places a hold for the amount, and a capture, which actually transfers the funds.<br />
To run an authorization, pass in an additional parameter authMode=AUTH_ONLY.<br />
<br />
Set Variable [$result Value:<br />
CCProcessPayment(<br />
gatewayID,<br />
password;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"firstName=" & Payment::First;<br />
"lastName=" & Payment::Last;<br />
authMode=AUTH_ONLY)]<br />
<br />
'''Returns''': a verification code from the payment gateway service if the order is successful, or "ERROR" if there was a problem<br />
<br />
After running an authorization, run the appropriate '''CCProcessAuthorizedPayment'''. Pass in the previousTransactionId from the transaction ID you received from the process with authMode.<br />
<br />
{{Template:E4 Optional Parameters}}<br />
<br />
<pre>Set Variable $result Value:<br />
CCProcessAuthorizedPayment(<br />
gatewayID,<br />
password;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre><br />
<br />
The dollarAmount is not required to process the authorized payment.<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
gatewayID;<br />
password;<br />
chargeAmount;<br />
"";<br />
"";<br />
"swipe=%B1234123412341234^LAST/FIRSTM^1112101000000000011100111000000?;1234123412341234=11121010000000000111?";<br />
"firstName=" & Payment::First;<br />
"lastName=" & Payment::Last;)]<br />
</pre><br />
<br />
=== Voiding Transactions ===<br />
<br />
Variable [$result; Value:<br />
CCVoidPayment (<br />
gatewayID ;<br />
password ;<br />
previousTransactionID;<br />
amount=refundAmount)]<br />
<br />
Voids a previously processed payment. The previousTransactionID should be the transaction ID of the transaction you wish to void. This value is returned by the CCProcessPayment function. Alternately, you can use the CCLastPaymentTransactionID function to get the transactionID of the last processed payment.<br />
<br />
Note that CCVoidPayment will only work on orders that have not settled yet, which means that it will generally only work on payments made that same day. To void settled orders, use CCRefund instead.<br />
<br />
'''Returns''': the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem<br />
<br />
See also: CCLastPaymentTransactionID: the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem (use CCLastError for more detailed information about the nature of the error).<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|gatewayID|password}}<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/MirrorSync_advanced_topicsMirrorSync advanced topics2014-01-16T18:37:15Z<p>Sarah: Updated instructions for XML import</p>
<hr />
<div>Welcome to the advanced section of the MirrorSync documentation! This guide will help you customize MirrorSync to suit your development needs, and provide detailed instructions for various situations. If you would like a good general overview of the software, please read through [[MirrorSync basic setup]] first!<br />
=== Deployment questions===<br />
<br />
====How do I uninstall MirrorSync?====<br />
To uninstall on Mac, run the 'Mac Uninstaller.pkg' that comes with the MirrorSync. On Windows, run 'C:\Program Files\360Works\Uninstall.<br />
<br />
====Installation for hosting providers====<br />
To install multiple instances of MirrorSync, choose the Hosting provider option in the installer. This is exactly the same as the regular installation process, except that it will allow you to rename the instance of MirrorSync. You can continue running the installer as many times as you like, once per client, renaming each instance to something unique. These copies can then be managed via the 360Admin utility, which is found either in your Program Files or Applications folder. When installing additional instances of the application, only a single Tomcat process will be installed which is shared by all of the MirrorSync instances.<br />
<br />
We recommend you use the installer. We at 360Works use the installer for our hosting clients as well, and find it easy to update and manage. If you are curious as to what the installer actually does, it modifies and adds the following:<br />
<br />
* Creates a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows that is readable and writeable.<br />
* Downloads and installs an instance of [http://tomcat.apache.org/download-60.cgi Tomcat 6] into that folder. (Only one copy of Tomcat is installed, regardless of how many copies of MirrorSync are running)<br />
* Copies and renames the installer's MirrorSync.war, which deploys the web app, as well as the other supporting material into the folder.<br />
* Adds a launch daemon in Library/LaunchDaemons in OS X, or creates a Windows Service to automatically start Tomcat.<br />
* Modifies the http.conf file for Apache to allow for URL redirection. If using Windows with IIS, we create an ISAPI filter or a URL Rewrite rule for the URL redirect.<br />
* Copies a lightweight Admin Utility JAR file to manage Tomcat to either C:\Program Files\360Works or /Applications.<br />
<br />
If upgrading from an older version of MirrorSync, we'll copy over the SyncData and remove the URL redirects for the old MirrorSync.<br />
<br />
If you prefer MirrorSync to be deployed to your own instance of Tomcat that you've set up, please note and follow these instructions:<br />
<br />
# Create a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows. Make sure that it is readable and writeable to the process that Tomcat is running as. This is where MirrorSync stores its private data including the internal sync database and the stored configurations. If you have a strong preference for locating this someplace else, because of disk space for example, set the '360directory' system property to point to some other path.<br />
# Rename the MirrorSync.war file to whatever name you'd like the instance to run as for your hosting customer, ie. 'CustomerXSync.war' If you decide to run multiple instances of MirrorSync with the same name (using multiple instances of Tomcat), you'll need to set '360directory' separately for each Tomcat instance, otherwise those multiple instances will overwrite each other's private data.<br />
# Drop that .war file into the webapps directory in your Tomcat instance.<br />
# Modify the the MirrorSync.xml context descriptor and set the administrative username and password for MirrorSync. In Tomcat 6, this file is automatically written to the Tomcat/conf/Catalina/localhost. If you are running Tomcat 7, the file is located in the webapps/MirrorSync/META-INF/context.xml file, or you can follow the instructions at http://tomcat.apache.org/tomcat-7.0-doc/config/host.html regarding copyXML to get the same behavior as Tomcat 6 (we recommend doing this, so that you don't lose the context.xml file every time the application is redeployed).<br />
# If necessary for your configuration, set up URL forwarding from IIS / Apache to your Tomcat connectors. [http://tomcat.apache.org/tomcat-6.0-doc/index.html See tomcat documentation on how to do this].<br />
<br />
==== Split server deployments ====<br />
If your FileMaker deployment is split onto multiple machines, we recommend installing MirrorSync on the FileMaker Server machine. This allows the download database feature in MirrorSync to work, which greatly simplifies deployment to end users. If you will not use the download database feature, and you do not plan on sending download URLs to your users, then install MirrorSync on the web server, for maximum speed during syncing.<br />
<br />
Regardless of which computer you install on, be sure that when you are configuring MirrorSync, you specify that the MirrorSync / FM Server machines are on different computers. This option is on the first screen in the new configuration process.<br />
<br />
====Does MirrorSync work with runtime versions of FileMaker Pro?====<br />
MirrorSync is untested and unsupported for use in this configuration. In addition, the legal licensing agreement for creating runtime versions of FileMaker specifically disallows any automated transfer of data between the runtime version and FileMaker Server. This restriction means that no sync process can legally be used to transfer data between the runtime edition and FileMaker Server, whether that is from a 3rd party or a home-grown automation process. Contact your FileMaker Business Account Manager for volume pricing on FileMaker Pro licenses.<br />
<br />
====What if I need to redeploy FileMaker Server?====<br />
If using a Mac, no additional steps should be required. However, if you are running Windows, you'll want to rerun the installer for MirrorSync.<br />
<br />
<div id="upgradeFrom1"></div><br />
====I am running MirrorSync 1. What do I need to do to upgrade to 2?====<br />
Any extra configurations or devices you purchased with MirrorSync 1 will carry over to MirrorSync 2 after purchasing the upgrade.<br />
<br />
# First, have all of your offline users run a sync. They will need to replace their offline files with new versions, so this will prevent them from losing any data.<br />
# MirrorSync 2 requires a creation timestamp field, in addition to the modification timestamp. Create that field if you do not already have one, and be sure to add it to all the MirrorSync layouts.<br />
# Run the MirrorSync installer. MirrorSync 1 configurations will not be preserved, so you'll need to create new configurations and distribute new copies of the files to your users. The good news is that since you already have all of your sync layouts ready to go, and also since MirrorSync 2 automatically detects foreign keys (requires FileMaker Server 12 or later), this shouldn't take much time at all.<br />
# Download new copies of the file for your users, and enjoy all the great features and speed of MirrorSync 2!<br />
<br />
=== Networking questions ===<br />
<br />
====Can MirrorSync send encrypted data? What about SSL enabled FMS?====<br />
<br />
Yes, it can. To make sure data is encrypted, you'll need a valid SSL certificate installed on the web server where MirrorSync is running. This will ensure that all plain-text data is sent and received encrypted with SSL. To sync container data using SSL, first set up FileMaker server as SSL enabled ([http://www.filemaker.com/downloads/documentation/fm12_security_guide_en.pdf see page 20 of these docs]). After doing so or if FileMaker Server is already is SSL enabled, check the SSL checkbox when configuring MirrorSync. <br />
<br />
If you get an error saying that you have a self-signed certificate, then you will need to follow the [[Custom SSL Certificate setup instructions]].<br />
<br />
<br />
====I need my database to be HIPPA compliant, what should I do with MirrorSync?====<br />
HIPPA compliance depends on a large number of requirements. However, one of those requirements is to transmit only encrypted data. See the question above if you experience difficulties. Please keep in mind that encryption is one piece of HIPPA compliance, so consult the [http://www.hhs.gov/ocr/privacy/ Department of Health and Human Services] for more information.<br />
<br />
<br />
====What ports are required for MirrorSync? Can I change them?====<br />
MirrorSync transmits container data on port 5003, which is the regular port for communication betwen FileMaker Pro and FileMaker Server. All other field types (text, number, date, time, timestamp) are transmitted using regular HTTP communication, which typically runs on port 80, or port 443 if SSL encryption is being used. These port numbers are set in your web server configuration (IIS on Windows or Apache on OS X), and can be customized to any value you prefer. A good way to test this is to test the FileMaker Web Publishing Engine - if the URL 'http://yourServer:somePort/fmi/xml/FMPXMLRESULT.xml?-dbnames' returns an XML list of database names, then it should work for MirrorSync as well.<br />
<br />
====Will MirrorSync work on a VPN?====<br />
Yes. MirrorSync runs over standard HTTP protocols (which are VPN compatible) for non-container data, and standard FileMaker protocols (which are also VPN compatible) for container data.<br />
<br />
====My solution is behind a firewall. Will MirrorSync still work?====<br />
MirrorSync communicates with FileMaker Server using a web viewer, so as long as the firewall allows standard HTTP traffic on port 80 (almost all firewalls are configured to allow this), all of your sync devices should be able to access it through the firewall. The exception to this is container fields. If you are syncing container fields, you will need to make sure that port 5003 (FileMaker's standard port) is open on the firewall, because the client needs to connect as a guest of the server to transfer container data.<br />
<br />
<div id="nat"></div><br />
<br />
==== Is MirrorSync compatible with Network Address Translation (NAT)? ====<br />
Yes. When configuring MirrorSync, select the option that says 'My internal and external IP addresses are different.' This will write the sync script so that if it detects it's running on the same LAN as MirrorSync, it will use the internal IP address, and if it's running outside the MirrorSync LAN, it will automatically switch to the external IP address.<br />
<br />
<br />
<br />
<br />
===Primary key / serial numbers===<br />
<br />
====What is the difference between 'MirrorSync-managed' and 'Developer-managed' primary keys? Do I need to change how I do my primary keys? Which one should I pick? ====<br />
Before answering this question, it's first necessary to explain why primary keys are a complex issue with synchronization. With traditional incrementing serial numbers, one database might have records numbered 1 through 10. Another database might have records 1 through 50. If we create a new record on the first database, it will get assigned the next number in the sequence (11). However, if we try to write that record to the second database, it will conflict with record 11 that already exists there. Here are several approaches to solving that problem:<br />
# '''Use Universally Unique Identifiers (UUIDs) as primary keys'''. These are typically long, 36-character strings that look like this: "D2EF9F69-5DEA-4FE3-9095-162C77F76FBF". They are sufficiently random to statistically eliminate the possibility of duplicate values. This makes them ideally for syncing databases - you can safely write records from one database to another without worrying about conflicting IDs. MirrorSync (and most other sync frameworks) supports UUIDs.<br />
# '''Combine a traditional serial number with some delimiter''', such as each user's initials or a file ID. This way, user 1 would have primary keys "1.1", "1.2", "1.3", and so on. User 2 would create primary keys "2.1", "2.2", "2.3", etc. This has the advantage of being shorter and more readable than UUIDs, but the added management consideration of assigning unique identifiers to each user. MirrorSync can manage this for you, as explained later.<br />
# A variation on the second solution would be to '''assign each user a particular numeric range''', so that user 1 generates primary keys in the range of 1-10,000; user 2 generates primary keys 10,001-20,000; and so on. This has the advantage of pure numeric values (instead of text), but the disadvantage of the possibility of conflicts if a user exceeds the expected number of records. MirrorSync can manage this approach as well.<br />
# A very different approach is to '''allow conflicting primary keys to exist on each separate database, without ever writing those primary keys to other databases'''. When record #11 is written from the first database to the second (in our original example), instead of being written with primary key 11, it is written with primary 51 (the next number in the sequence on the second database). This has the advantage of the shortest possible primary keys, which are pure numeric values, with no possibility of conflicts. It is also the way that the majority of existing databases are designed. MirrorSync supports this method (and is the only sync framework that does, to our knowledge). It creates an internal table to translate between the primary keys on all database that are syncing, so that when record #11 is later updated, MirrorSync knows to change record #51 in the second database. MirrorSync also re-writes foreign keys when they are written from one database to another, so that foreign keys that contained '11' on the first database will be re-written with '51' in the second database.<br />
<br />
Options 1, 2, and 3 are considered ''''Developer-managed'''', because MirrorSync writes the primary keys unmodified between the databases being synced. It is the developer's responsibility to pick some scheme that ensures that the same primary key is never used for different records on different databases. There are other variations on the same theme (ie. one database gets odd numbers and the other gets even numbers), but they all are treated the same by MirrorSync.<br />
<br />
Option 4 is considered ''''MirrorSync-managed'''.' The developer is not responsible for the uniqueness of primary keys across different databases; MirrorSync takes care of this for you.<br />
<br />
As to which you should pick, the answer is usually this: If your FileMaker database is currently using UUIDs, use developer-managed. If your database is written using traditional serial numbers, you should use MirrorSync-managed. However, if you need 'user-friendly' numbers for things like invoice numbers, job numbers, or check numbers, [[#writebacks|read the next FAQ]] on user-friendly serial numbers before making a decision.<br />
<br />
If you are building a new database and can use whichever approach you want, here are the relative advantages:<br />
* Serial numbers are more efficient because they are smaller. [[#What can I do to speed up syncing?|<br />
See the performance section of this documentation]] for more discussion on this.<br />
* UUIDs are easier to use if you need to ever sync or import manually, or switch to some other sync framework.<br />
<br />
<div id="writebacks"></div><br />
<br />
====What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?====<br />
The problem with MirrorSync-managed serial numbers is that they are not suitable for user-visible numbers, such as invoice numbers. That's because the primary key will be different on one device than another. If you're using the primary key serial number as your invoice number, it is clearly a problem if your invoice number is different between your laptop and the server!<br />
<br />
There are several solutions to this problem. One of the first things to establish is whether your database uses a single field as both the primary key and the user-visible value (we'll refer to it as the 'invoice number'). It is always preferable (even when not syncing) to have these be separate fields from each other. Invoice numbers / job numbers / user visible numbers should NOT be what you use as a primary key in your database. Primary keys are internal database identifiers, and should not do double-duty as a user-readable value.<br />
<br />
If the fields are separate, the problem becomes simpler to solve, because you have the flexibility to change the value of the invoice number without breaking relationships. See the section below on write-back values for the recommended approach.<br />
<br />
If the same field is being used for the primary key and the invoice number, and if it is feasible to split this into two separate fields (one for relationships, and one for display/searching), you should do so. Unfortunately, this can sometimes be a very big job - creating the new field is easy, but then you either need to find every place that that field is used in the user interface and point it to the newly created invoice number field, or else you need to find every place that it is used in the relationship graph and re-point that to the newly created primary key field. If you do not want to do this, then see the section below on MIRRORSYNC_CLIENTID for the recommended approach.<br />
<br />
{{mbox <br />
| type = warning<br />
| text = <b>One mistake you should be careful to avoid is this:</b> If your database is currently designed with serial numbers for primary keys, do not try to short-cut the solution by simply creating a new UUID field and try to trick MirrorSync into using that as your primary key. MirrorSync won't re-number your foreign keys, which means that the wrong children records will point to the wrong parent records when the records are synced with the server.}}<br />
<br />
===== Write-back values for user-visible numbers =====<br />
Let's say that you have a UUID as your primary key field, as well as an invoice number field. Using the write-back approach, the invoice number field will be blank when a record is created in an offline file. When that invoice record is synced to the server, it will get assigned the next invoice number, and that number will be written back to the invoice number field on the offline file. This approach does not work unless the invoice number field is separate from the primary key.<br />
<br />
Advantages of this approach:<br />
* Invoice numbers are in a simple, short numeric sequence, just like they would be without syncing.<br />
<br />
Disadvantages:<br />
* The offline file does not get an invoice number until the record is synced for the first time.<br />
<br />
To use this approach, follow these steps:<br />
* If you do not already have a serial number field in your table, create one. If you have a serial number which is used as a primary key, that's usable. We'll call that field 'serialNumber' in our example.<br />
* Define your invoiceNumber field this way: <code>If( Get( MultiUserState ) = 2; serialNumber; "" )</code>. This will leave the invoice number blank when working offline, but fill it in when connected directly to the server.<br />
* In the primary key selection screen in MirrorSync, select invoiceNumber as the write-back field. This will cause MirrorSync to write invoiceNumber from the server back to the offline file when the record is first synced.<br />
* Your choice of MirrorSync-managed or Developer-managed is unaffected by this setting; pick appropriately depending on whether you are using serial numbers or UUIDs as your primary key.<br />
<br />
===== MIRRORSYNC_CLIENTID for user-visible numbers =====<br />
Let's say that you have a single serial number as your primary key, which is doing double-duty as an invoice number field. You can use the $$MIRRORSYNC_CLIENTID global variable to help. Using this approach, MirrorSync ensures that each file being synced gets assigned a unique sequential number, starting from 1. You can use this number in conjunction with a traditional serial number to create a unique number than can be used as a user-visible field as well as a primary key. The serial numbers will either be text (ie. "1.1", "1.2", "1.3"…) or numeric (10,001 for user 1, 20,001 for user 2, 30,001 for user 3…).<br />
<br />
Advantages of this approach:<br />
* Reasonably short user-visible numbers<br />
* IDs are assigned immediately upon record creation, without needing to wait for syncing<br />
<br />
Disadvantages:<br />
* Offline users must do an initial sync before they can create records.<br />
* Requires a startup script to run, which means it won't work with custom web publishing applications.<br />
* IDs are not sequential, so you can't assume that an ID with a higher value was created before or after another ID.<br />
* If you are using numeric version, limits users to creating a fixed number of records before they start conflicting.<br />
* If you are using text version, you must switch all primary key and foreign fields from 'number' type to 'text.'<br />
* Setup is a bit more complex than write-back fields.<br />
<br />
To use this approach, follow these steps:<br />
* Set the 'MirrorSync setup' script as your startup script. If you already have a startup script, call the 'MirrorSync setup' script from your existing script. This will set the $$MIRRORSYNC_CLIENTID global variable. This clientId field is stored in the MirrorSync table, and is assigned when the user does their first sync. Each synced database will get a unique, sequential clientId. Manually run the script now to set that global variable before proceeding.<br />
* We assume you have a serial field called 'serialField'. Start off by duplicating this field, to create a new field called 'serialField copy.'<br />
* Change serialField to an auto-enter calc. Uncheck the box that says 'Do not replace existing value'. Also make sure that the 'Prohibit modification of value during data entry' is unchecked. Set the formula to one of the following:<br />
For text keys, use this formula (feel free to modify as desired):<br />
<pre><br />
$$MIRRORSYNC_CLIENTID & "." & serialField copy<br />
</pre><br />
for numeric keys, use this formula (replace whatever number you want instead of 10,000 to give wider or narrower range of numbers):<br />
<pre><br />
$$MIRRORSYNC_CLIENTID * 10000 + serialField copy<br />
</pre><br />
If you use the text version, be sure to change the field type from number to text. Also change all foreign keys that relate to it to text.<br />
* For primary key configuration in MirrorSync, select Developer-managed.<br />
<br />
<br />
<div id="compoundkey"></div><br />
==== How do I configure and use two foreign keys as a primary key? ====<br />
This is a common configuration for join tables in many-to-many relationships. In the primary key configuration screen, use the drop down menus to select the two foreign keys.<br />
<br />
Please keep in mind primary keys need to be unique. If using two foreign keys, there may be an instance where an error occurs about a duplicate node ID, since FileMaker is not validating the fields together and making sure they are always unique in a table. To avoid this, make sure:<br />
<br />
#Ensure that the combination of two foreign keys only ever occurs once in the database.<br />
#If you need to be able to have multiple join table records with the same foreign keys, add a regular serial number field to the join table and use that as the primary key, instead of the compound foreign keys.<br />
# The foreign key fields must both have the 'Not empty' validation in order to appear in the pull-down menu of eligible fields. If your join table needs to have foreign keys that may be empty, you should add a traditional single primary key to the table instead of using compound foreign keys as an identifier for MirrorSync.<br />
<br />
===Configuration questions===<br />
<div id="differentfile"></div><br />
==== Does MirrorSync need the databases being synced to be identical? ====<br />
No, not in MirrorSync 2. MirrorSync is able to sync between databases with completely different tables and fields from each other. In addition, it can sync just a subset of records, fields, and tables. If you are syncing different databases, for example a dedicated mobile file with a much larger server database, select the option 'Sync with a separate mobile file' (for FileMaker Go) or 'Sync with a separate server file' (for server-to-server sync). With this option selected, MirrorSync will allow you to match up your layout and field names with a simple drag and drop interface.<br />
<br />
====Why does MirrorSync need to know about foreign keys?====<br />
MirrorSync uses foreign keys for two purposes. If you are using MirrorSync-managed primary keys, then it needs to know about the foreign keys because it needs to rewrite them when it writes between databases (see the primary key section above).<br />
<br />
In addition, even if you're using developer-managed primary keys, MirrorSync needs to know about relationships so that it can sync parent tables before children tables. This allows validation rules that check referential integrity to work correctly.<br />
<br />
MirrorSync 2 adds a new feature that automatically detects foreign keys, if you are using FileMaker 12 or later, so this step should not add any time to the configuration process. If you are using FileMaker 11 AND you are using developer-managed primary keys AND if you do not have any referential integrity validation making sure that foreign keys point to valid parent records, you can safely skip this step.<br />
<br />
====I'm not seeing my databases from the Choose database button. What's happening?====<br />
Make sure XML publishing is enabled for the account you are using in MirrorSync. Also be sure the database is accessible from the machine you are installing MirrorSync on.<br />
<br />
To test the XML Web Publishing Engine, try going to the URL <code>http://yourServer/fmi/xml/FMPXMLRESULT.xml?-dbnames</code>. You should see an XML document listing the databases in FileMaker Server. If you do not, or find a 404 or 401 error, then the XML Web Publishing Engine may not be configured correctly. Contact FileMaker tech support for help getting this running.<br />
<br />
If there is an authentication required at that test URL, try disabling IIS authentication. FileMaker Server authenticates its password-protected databases; however, this method disables the IIS authentication layer. This will also disable authentication for other websites that are using IIS on that server.<br />
<br />
# From the Control panel, navigate to Administrative Tools > Internet Information Services (IIS) Manager<br />
# Select the website in IIS and choose Action > Properties<br />
# Navigate to the Directory Security pane, and select Edit for authentications. This button may differ in various Windows versions.<br />
# In the Authentications Methods pop up:<br />
#* Make sure Anonymous Access is enabled<br />
#* For Authenticated access, disable the authentication methods.<br />
# Press OK<br />
<br />
<br />
==== Configuration without FileMaker Pro Advanced ====<br />
<br />
Since FileMaker Pro does not have the ability to copy and paste tables, you'll need to follow these instructions to create the MirrorSync table.<br />
<br />
*Locate the XML schema that came with your MirrorSync download.<br />
*Open FileMaker Pro and navigate to File -> Import Records -> XML Data Source.<br />
*In the "Specify XML and XSL Options" window, choose the "File" radio button, then click "Specify...".<br />
*Navigate to your MirrorSync download folder and choose the MirrorSync.xml file from the XML Schema subfolder.<br />
*Click continue to bring up the Import Field Mapping window. <br />
*Open the "Target" drop down menu, and select "New Table ("MirrorSync")"<br />
*Verify that the source fields and target fields have been matched correctly.<br />
*Click import.<br />
<br />
After the table is created, you'll need to modify some of the fields:<br />
*Navigate to File -> Manage -> Database...<br />
*Navigate to the "Fields" tab, highlight the '''id''' field and click the "Options..." button.<br />
*Check the box next to "Serial Number." Set it to generate on creation.<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the boxes next to "Not Empty" and "Unique Value" then press OK.<br />
*Next, highlight the '''modstamp''' field and click the "Options..." button.<br />
*Check the box next to "Modification" and ensure that the drop down menu says "Timestamp (Date and Time)."<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the box next to "Not Empty" then press OK<br />
*Next, highlight the '''lastErrorMessage''' field and click the "Options..." button.<br />
*Navigate to the "Storage" tab and check the box next to global storage and press OK.<br />
*Repeat the last two steps to make '''webServerResponse, _gSync1, _gSync2, _gSync3, _gSync4, _gLastInsertTable''', and '''_gLastInsertResult''' all be global fields. <br />
*Finally, highlight the '''container''' field, and select "Container" from the "Type" drop down menu, next to the "Options..." button.<br />
You are now finished manually configuring your MirrorSync table. Click the OK button to close the database management window, and return to the MirrorSync configuration. (Be sure to save your changes!)<br />
<br />
<div id="separation"></div><br />
<br />
====Separation model / multiple file solutions====<br />
MirrorSync will work fine with multi-file solutions. You need to make sure that one of the files in your solution has a reference to every table that you want to sync (for separation model solutions, it is better to use the data file than the UI file, because MirrorSync stores some internal data in a new MirrorSync table that it creates in the file). When configuring MirrorSync, use this file. When using the MirrorSync download feature, be sure to select the multi-file option so that your offline users will receive all of the files for the solution.<br />
<br />
====How do I configure External SQL Source (ESS) tables?====<br />
MirrorSync supports ESS tables, but it's very slow compared to using MirrorSync to simply sync the database from the external SQL database into your FileMaker Server. We do not recommend ESS unless syncing is not an option for some reason.<br />
<br />
If you would like to use ESS tables, there are additional steps. First, configure MirrorSync in its entirety. You should be able to select your ESS tables and files in the configuration utility. After you have pasted the last script step, download a copy of the file as usual. <br />
<br />
At this point, you need to make some modifications for the file to work offline. Open the downloaded copy, and make the following modifications to the local copy ONLY! Do not run the sync yet.<br />
<br />
* First, delete the data source. This is vital to preventing duplicate records and other artifacts of using ESS. Open File > Manage > External Data Sources and delete the OBDC data source.<br />
* Next, open the File > Manage > Database and navigate to the Tables tab. Copy any ESS tables. Then delete them. Make sure NOT to delete the table occurrences. After all the italicized tables are gone, paste the tables back in. This ensures they are local FileMaker files, not references to external data.<br />
* Make sure the primary keys, modification timestamps, and creation timestamps are correct. The primary key needs to be an auto-entered serial number or generated UUID.<br />
* Open the relationships tab in the File > Manage > Database and relink the missing tables.<br />
<br />
You can now distribute this file for synchronization to your users. Make a copy of this file and send it to each user who needs a copy. These copies are then ready for synchronization.<br />
<br />
<br />
====I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?====<br />
After converting your file, you'll need to edit the configuration and replace the MirrorSync script steps with ones generated for the FileMaker 12 file. This is due to the fact that the "Insert from URL" script step doesn't exist in FileMaker Pro 11.<br />
<br />
===Sync questions===<br />
<br />
==== Does MirrorSync work with timezones? ====<br />
Yes and No.<br />
<br />
For offline users who are syncing, Yes. When MirrorSync gets a list of all modifications, it will automatically detect the offline user's timezone and clock drift and compensate for it.<br />
<br />
For server-to-server sync, Yes. MirrorSync can detect FileMaker server's current time and compensate for it, just like it does for offline users.<br />
<br />
For non-syncing users connecting directly to FileMaker Server, No, not automatically. You'll need to perform a small work around to make this work. It gets a little complicated, so an example makes it more clear. Let's say your FileMaker Server is hosted in New York. A user in New York runs a sync at 12:30 PM Eastern Time. 30 minutes later, a user in San Francisco modifies a record on the server at 10 AM Pacific Time (1 PM Eastern Time). Due to the way that FileMaker Server works, that modification timestamp on the server in New York will say 10 AM. It will not be converted to Eastern Time, nor will FileMaker Server store any time zone information for anybody to tell that it was actually representing Pacific time. Essentially, it's just an incorrect value. When the next sync runs, MirrorSync is going to request records modified since the last sync at 12:30 PM, which is going to miss the change made by the San Francisco user, even though it was made since the last sync.<br />
<br />
The solution to this problem is very easy - it actually takes less time to do than it did to read that explanation! Let's say that your table contains a regular modification timestamp called 'Modification timestamp'. Create a new field called 'Host modification timestamp' (or whatever you prefer), and set it to auto-enter this calculated value:<br />
<pre><br />
Let( x=Modification timestamp; Get ( CurrentHostTimeStamp ) ) //Change modification timestamp to be whatever the name of your modification timestamp field is<br />
</pre><br />
<b>Be SURE to uncheck the box titled 'Do not replace existing value of field (if any)'.</b><br />
<br />
Use this field as the modification timestamp in the MirrorSync configuration process, instead of the regular modification timestamp.<br />
<br />
This works by using the FileMaker Server clock, instead of the user's clock, for the modification timestamp. Now, when the San Francisco user modifies a record at 10 AM Pacific Time, FileMaker Server will store 1 PM (the server's local time when that change was made) in the Host modification timestamp field, and MirrorSync will work with time zones correctly.<br />
<br />
====Why can't I transfer my database to another computer after I've synced it?====<br />
The MirrorSync server stores information about each device that syncs with it. This includes the primary key, as well as the count of modifications for that record on that particular device. If this file were to be synced from two different devices, this information would conflict and cause problems. If you do try to send a database to another device and sync it, an error message will appear and the sync will be prevented.<br />
<br />
====Can I share a device among multiple users?====<br />
Yes, but…<br />
<br />
If all users on that device log in with the same username, then it's <i>probably</i> OK, as long as you make sure that you are not using record level access privileges on the offline device that would grant different record access to different users.<br />
<br />
If you want each user who shares a device to log in with different usernames, then the solution is to put a separate copy of the file on the device, one for each user. Make sure that each user is only able to login to the file that is assigned to them.<br />
<br />
MirrorSync prevents multiple users with different usernames from sharing the same offline file, because if record level access privileges or script filters were configured differently for each user, that would lead to the sync process incorrectly deleting the wrong records on the server, which would be very bad.<br />
<br />
====Does MirrorSync sync container fields?====<br />
A:Yes, MirrorSync works with FileMaker container fields. Container fields do take longer than other field types to synchronize, so remove them from your sync layouts if you don't need them to be synced.<br />
<br />
<br />
====What about SuperContainer? Does MirrorSync work with that?====<br />
Yes, it does. However, with SuperContainer the approach is very different. Only the URLs are synchronized, not the actual files - they remain on the SuperContainer server. The advantage is syncing is very fast - there is no binary data being transferred. The disadvantage is that you'll only have access to the files stored in SuperContainer when you have working network access from your computer or iOS device.<br />
<br />
====Does MirrorSync sync external container fields?====<br />
Yes, MirrorSync works with external container fields. There are no extra steps to take when syncing with FileMaker Pro or FileMaker Server. If you are using external container fields on an iOS device, there are a few steps after configuration that are required.<br />
<br />
#Download a copy of the database from MirrorSync or FileMaker Admin<br />
#Open the copy on a computer, and navigate to File > Save a copy as...<br />
#Under the type drop down, choose "self-contained copy (single file)"<br />
<br />
This ensures the copy of the file embeds the containers into the file for easy use with FileMaker Go and offline functionality. <br />
<br />
PLEASE NOTE: there is an unfortunate behavior in FileMaker in this process: when saving the self-contained copy, FileMaker updates the modification timestamp for every record that has an external stored container field. That's not a problem normally, but when used with MirrorSync, it will make the initial sync very slow. The reason for this slowdown is due to MirrorSync assuming that all of those records have been modified on the client, so it writes all of the server data to the client (including the container data). <br />
<br />
The workaround for this is to uncheck the modification timestamp auto-entry before saving the self-contained copy, and then turn it back on after the copy has been saved. This modification timestamp behavior has been reported to FileMaker, Inc. and will hopefully be resolved soon.<br />
<br />
====Does MirrorSync require users to sync with full access accounts?====<br />
<br />
No. MirrorSync requires a full access account only once: to paste in the table, scripts, and layout. When users run the sync, they will use their own user account privileges, with whatever access that grants them. See the '[[#Customizing MirrorSync|Customizing MirrorSync]]' section below for tips on restricting user accounts.<br />
<br />
====Does MirrorSync do conflict resolution?====<br />
Yes, MirrorSync has robust conflict detection and field-level merging (added in version 2). It will detect when the same record(s) are modified on both database and take action. There are two settings in the configuration client that will control how this works:<br />
<br />
* <b>Merge the changes together</b>: If MirrorSync sees that all of the changes made in the databases were to different fields (ie. firstName on the server and lastName on the client), it will automatically merge the changes together. It will not tell the user that a conflict occurred, it will just write the merged record to both the server and the client. If any changes were made to the same field, it is treated as a conflict and not merged.<br />
* <b>Flag the edit as a conflict</b>: MirrorSync will treat all modifications to the same record as a conflict, regardless of whether they were made to the same fields or different fields.<br />
<br />
If a conflict occurs, then MirrorSync will resolve it based on the next configuration option:<br />
* <b>User picks:</b> MirrorSync will present a web-based interface to the user, summarizing all conflicts and showing them exactly which fields were changed on both databases. It color-codes the actual sections of text that were changed, making it easy for even inexperienced users to make the best choice. The user is able to pick one entire record over another, pick individual fields from each record, and even manually edit the result to combine changes from both records. They also have the option to automatically select the most recent change (see next option).<br />
* <b>Most recent change wins:</b> MirrorSync will pick whichever record was last modified as the winner of the conflict. If Joe changes a record on his iPad at 3:00 PM, Kate changes the same record on her iPhone at 3:30 PM, and Tom changes the record on the server at 4:00 PM, then when Joe or Kate sync their database, Tom's record will be selected as the winner, regardless of when Joe and Kate do their sync.<br />
* <b>Hub always wins</b>: MirrorSync will always pick the value on the hub (typically FileMaker Server) as the conflict winner, regardless of other considerations. This is not generally recommended, because it is essentially first-sync wins behavior: Whoever syncs to the hub first will win conflicts with other offline users who modify the same record and sync. This setting can be useful if changes made by directly connected users should be given priority over offline, syncing users.<br />
* <b>Email administrator</b>: This is very similar to 'User picks', except that instead of the user who is doing the sync deciding, an e-mail is sent to the administrator email address specified in the configuration. The administrator can resolve the conflict using the same web-based user interface described above, after which the user will be able to sync normally.<br />
<br />
====Is MirrorSync transactional? What happens if the connection is lost while syncing?====<br />
MirrorSync is not 'transactional' in the strictest sense. If the connection is dropped during a sync, it is possible for records from one table to be written to the server, while records from another related table may not be written. However, MirrorSync keeps track of which records have been written and which ones have not, and it will resume from where it was on the next sync and complete everything as if the first sync had finished. If a record on the server cannot be written because it is being edited, the offline user will get a warning error message telling them this. MirrorSync will continue to retry that edit operation each time the sync script is run.<br />
<br />
====Can I use external authentication with MirrorSync?====<br />
Yes, MirrorSync supports externally authenticated accounts with no modifications. So long as the username on the local copy matches the username on the server, you can set up one password for local access and another for external authentication with the server. The passwords do not need to match between the local file and the hosted file.<br />
<br />
<br />
<br />
<br />
=== Server-to-server sync ===<br />
<br />
==== How do I set up server-to-server syncing? ====<br />
For the most part, the process for setting up server-to-client sync is almost identical to server-to-server sync. Here are a few differences to be aware of:<br />
* If you will be syncing container fields across a Wide Area Network (WAN), both servers must have public IP addresses, because they each make HTTP calls to the other.<br />
* In the spoke configuration, you select 'copy or clone of existing file' or 'separate file.' If the first option is selected, you don't actually put the file on the other server during the setup process - go through the setup process, and when you're finished, save a copy or clone from the hub server using the MirrorSync download feature and upload it to the spoke server. If you select 'separate file', then you will need to have the file up and running on the spoke server during configuration.<br />
<br />
==== How do I run a server-to-server sync? ====<br />
You do not use the MirrorSync script from within FileMaker, like a server-to-client sync. Instead, use the 'sync' button in the MirrorSync admin utility. Once you've run the sync and are satisfied that everything is working correctly, you may enable auto-sync by checking that box and specifying the frequency to run the sync.<br />
<br />
==== How can I be notified of a problem that occurs during server-to-server sync? ====<br />
There is an administrative e-mail address that is set during MirrorSync configuration. If you set this, you will receive e-mail notifications whenever the sync fails (or succeeds, depending on what granularity you set admin e-mails to). These e-mails are sent via Amazon Web Services, and thus do not require you to configure an SMTP server.<br />
<br />
===Performance questions===<br />
<br />
====How well does MirrorSync perform on slow networks?====<br />
MirrorSync is very efficient over slow networks, because it sends very little data other than the actual record changes, and it transmits this information in large chunks, which is more efficient. There are 3 HTTP request at the beginning of the sync, and usually 2 HTTP requests per table that contains any modifications. For example, if you have a 20 table solution, and there are changes in 5 of the tables, it will usually take 13 HTTP requests (3 + 2*5) to complete the sync. By comparison, the FileMaker home page takes 65 HTTP requests to load in a web browser.<br />
<br />
<br />
====My file is very large, and I want to give MirrorSync more memory allocation. How do I do this?====<br />
MirrorSync has a 512 megabyte allocation by default. This is typically sufficient for syncing change batches of around 200,000 records, although that number gets much smaller if the records contain a lot of information. Now divide that number by the number of devices simultaneously syncing - so if you expect up to 4 people to be syncing simultaneously, MirrorSync can probably handle up to 50,000 changes from each user with the default memory allocation. If you need more than that, you can increase the memory allocation by modifying the setenv file. Find the 512 and change it some new memory allocation, like 1024. The file is at:<br />
<pre><br />
Mac: /Library/360Works/Applications/bin/setenv.sh<br />
Win: C:\Program Files\360Works\Applications\bin\setenv.bat<br />
</pre><br />
<br />
====What can I do to speed up syncing?====<br />
MirrorSync is pretty fast without any special tweaking, but faster is always better. Here are some tips for squeezing out the best possible sync speed from MirrorSync:<br />
<br />
* SSD drives: MirrorSync does many thousands of tiny read and write operations when syncing large record batches. This type of usage will benefit greatly from the ultra-low latency of SSD drives. You will see a noticeable change in sync speed by installing MirrorSync on an SSD drive. You don't need to use an SSD for your entire hard drive - you can just put MirrorSync on the SSD by using a symbolic link in OS X or changing the install location on Windows. The SSD performance benefits will improve all sync operations, but it will be most noticeable when doing very small syncs with few or no changes, and initial syncs for large database with hundreds of thousands of records.<br />
<br />
* When MirrorSync fetches changed records from FileMaker Server, it requests all changes since 10 minutes prior to the last sync. This 10 minute overlap compensates for users whose clocks are slow. If you're using the Host modification timestamp trick outlined in the timezone section above, then the user clock doesn't matter, and you don't need this 10 minute overlap. You can get rid of it by editing the MirrorSync.xml file and change the 'fmServerOverlapSeconds' parameter from 600 (10 minutes) to 5 (5 seconds). The file is at:<br />
<pre><br />
Mac: /Library/360Works/Applications/conf/Catalina/localhost/MirrorSync.xml<br />
Win: C:\Program Files\360Works\Applications\conf\Catalina\localhost\MirrorSync.xml<br />
</pre><br />
<br />
* Use serial numbers instead of UUIDs, especially for large record sets with narrow tables. The difference between a 5 character serial number and a 36 character UUID adds up, especially when transferring large numbers of records that mostly consist of foreign keys, such as join tables. Don't make this change if you have a good reason for using UUIDs.<br />
<br />
* Container fields hold lots of data, require a guest connection to FileMaker Server over port 5003, and are sent individually instead of in batches like non-container data. If there are containers that you don't need to sync, remove them from the sync layouts. Removing all container fields will give much better sync performance, as well as eliminating firewall concerns, because MirrorSync does not need to connect as a guest of FileMaker Server.<br />
<br />
* If you want to just sync a subset of records, instead of the entire database, you can use either record level access privileges or scripted filters (see the customization section below for more details). Scripted filters are much, much faster then record level access privilege restrictions.<br />
<br />
* If you're on FileMaker 11, switch to 12 or later. All of MirrorSync's communication with FileMaker Server is via the XML Web Publishing Engine, and this was just not very fast in FileMaker Server 11. It is greatly improved in later versions of FileMaker Server.<br />
<br />
* Flag records instead of deleting them: MirrorSync 2 is very fast at detecting deleted records. However, it's always faster to sync edits and inserts than to scan for deletions, especially in large tables with more than 100,000 records. If you want to optimize performance, it might make more sense to flag records as being deleted instead of actually deleting them. That makes it into an edit operation, which is not affected by the number of records in the table.<br />
<br />
===Customizing MirrorSync===<br />
<br />
====I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?====<br />
That's a three-part question with a three-part answer. Just <b>syncing certain tables</b> is very easy: When you're configuring the sync using the MirrorSync configuration utility, only include layouts corresponding to the tables that you want to sync.<br />
<br />
<b>Syncing certain fields</b> is also very easy: Just don't include any fields on your sync layouts except the ones that you want to sync.<br />
<br />
<b>Syncing certain records</b> is only slightly less easy: Edit the 'MirrorSync Customization' script and follow the instructions in the 'FindChanges' documentation there to constrain the found set to just the records you want to sync for the current user. Remember that the script will be running as the user doing the sync, so you can use the Get( AccountName ) function to determine which records are available. <b>Be careful regarding the use of $$globalVariables</b> - they will work correctly for the duration of the current sync, but they will not still be set on the next sync (except for $$MIRRORSYNC_USERTOKEN - see next question).<br />
<br />
Any records that are excluded by your search criteria will not be synced to the user. In addition, if those records were previously synced, they will be deleted from the user's device. This makes it very easy to create check-in / check-out workflows with MirrorSync, where jobs are synced to iPads, completed, and then deleted from the device.<br />
<br />
To test your customization script, go to the sync layout that you want to test, show all records, and run the MirrorSync customization script. If you don't get the results you expect, use the Script Debugger to tweak it.<br />
<br />
Another approach to limiting record access is with FileMaker's record level access restrictions. Any restrictions you place on the user's privilege set will be respected by MirrorSync, and the user will only receive those records when they do a sync. Records which were previously visible which switch to non-visible will be deleted on the next sync. Keep in mind that scripted record filters will be much faster than using record level access privileges.<br />
<br />
If you decide to limit the synced records, you may choose to distribute an empty clone to your users instead of a full copy of the database. That way, the initial sync will only pull the records into their offline file that they have access to on the database. Keep in mind that if they have access to many thousands of records, that could make the initial sync slower than if you distributed a full copy of the database that already contains all of the record data, and let the initial sync delete the extra records.<br />
<br />
====How can I filter records on a per-user basis if everybody is logging in with the same Filemaker account?====<br />
Use the $$MIRRORSYNC_USERTOKEN to accomplish this. This is a special global variable that MirrorSync passes from the client to the server when a sync runs. You can set this global variable to whatever you want on the client, and it will be set on the server so that the MirrorSync customization script can use it when searching for records. This global variable is the one exception to the 'no global variables' rule for server-side filtering, so use it any way you want. You'll notice that it is nested in a conditional in the MirrorSync customization script that sets it. That 'If' statement prevents it from being set on the server, which is important because that would override the value sent by the client.<br />
<br />
====How can I tell if a record created in FileMaker Go has been synced with the server?====<br />
During configuration, select any field as a write-back value (see [[#writebacks | write-back values]] in the primary key section, above). Make sure that value is only set to auto-enter a value on the server, by checking that <code>Get(MultiuserState) = 2</code>. If the field is blank, the record has not yet been synchronized. If the field contains a value, then it was either created on the server, or created in FileMaker Go and synced with the server.<br />
<br />
Another approach you can take is by modifying the didInsert section of the customization script (see next question), but the write-back approach is significantly faster when syncing.<br />
<br />
====How can I run a script on the server when a record is synchronized?====<br />
Maybe you want to send an e-mail to an administrator when a user completes a delivery, creates a request for a quote, or deletes a job in production. To do these types of operations, modify the MirrorSync customization script. There is a section in the script for 'DidUpdate', 'DidInsert', and 'WillDelete'. Make sure you modify those in the 'Hub' section - it's very rare that these should be modified on the spoke. In the relevant section of the script, check the current layout, and if it's the one where you want to take action, go ahead and do whatever you want in this section. You can freely go to other layouts, do searches / inserts / updates / deletions, send e-mails, or take any other action, as long as you finish the script on the same layout and record where you started.<br />
<br />
If MirrorSync detects that the record was modified as a result of a 'DidInsert' or 'DidUpdate' script, it will re-do the client search, taking into account any scripted record restrictions in the 'FindChanges' section. For example, if you want jobs to be removed from the user's iPad when a record on the 'SyncJob' layout has its status changed to 'Completed', take these steps:<br />
# Modify the 'FindChanges' to exclude records whose status is 'Completed' when Get(LayoutName) = "SyncJob". (To do this type of search in FileMaker, enter Find mode, Set the status field to 'Completed', Omit the current record/request, and then Constrain Found Set)<br />
# Modify the 'DidInsert' section to blank out the modification timestamp when Get(LayoutName) = "SyncJob".<br />
# Do the same thing in the 'DidUpdate' section.<br />
<br />
Now, whenever an offline user updates or inserts a record in the 'SyncJob' table, the script will blank out the modification timestamp. This triggers a change, which causes MirrorSync to re-do the search, which will exclude the complete job from the search, which will automatically remove it from the iPad.<br />
<br />
You might ask, why blank out the modification timestamp? The answer is that it actually doesn't matter what you do, as long as you make some change to the record at all. Blanking out the modification timestamp is a harmless change, because FileMaker will immediately replace the blank value with a new timestamp. You could just as well set any field on the record to its current value, or make some more meaningful change, such as filling in a date field with the data that the job was completed.<br />
<br />
====I don't want users to see any dialogs when the sync runs, can I prevent them from showing?====<br />
Yes, set the global variable $$SILENT_MODE to "1" in the MirrorSync customization script. This will prevent MirrorSync from showing any dialogs unless an error occurs, and for required information like login and conflict resolution.<br />
* If you would like to also skip the login dialog, AND if you know the user's password (ie. if it's stored in a users table) OR everybody is syncing with the same account, you can hard-code the $$MIRRORSYNC_USERNAME and $$MIRRORSYNC_PASSWORD values in the MirrorSync customization script. If these are both non-empty values, then MirrorSync will not prompt the user to enter their password.<br />
* If you would like to prevent the conflict resolution dialog from displaying, pick any option other than 'user decides' in the conflict resolution section of the MirrorSync configuration process.<br />
<br />
==== I don't want users to see the MirrorSync window at all when a sync runs. Can I prevent that from showing? ====<br />
If you are running MirrorSync on FileMaker Pro, then yes. Set the $$MIRRORSYNC_HIDE_WINDOW variable to 1 in the MirrorSync customization script. This will move the MirrorSync window off-screen, where the user cannot see it. This is not recommended for large sync operations that will take longer than a few seconds, because without that status display, users may think that their computer is frozen.<br />
<br />
If you are running MirrorSync on iOS, then this cannot be hidden. That is because MirrorSync needs to open a new window to manipulate the found set without losing the current selection, and new windows cannot be hidden offscreen on iOS devices. The $$MIRRORSYNC_HIDE_WINDOW variable will be ignored on iOS.<br />
<br />
==== Can I block other MirrorSync dialogs from being displayed to the user, or change the wording? ====<br />
Yes. Using the MirrorSync customization script, all dialogs, even error messages, can be suppressed or modified. Look towards the bottom of the MirrorSync customization script, and you will see a section that includes a dialog for each type of message that is displayed to users during a normal sync. You may freely customize the message displayed to the user, or the title of the buttons (but be sure that the first button still has the same meaning, and the second button still has the same meaning). If you want to hide the dialog from showing, you can disable the script step that displays it, but you must decide which option you would like to select, and exit the script with that button number. You can use this technique to display messages to your users in their preferred language.<br />
<br />
====Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?====<br />
Yes, absolutely. First of all, we recommend setting the 'MirrorSync setup' script as your startup script, or calling it from the startup script. This will check to see if the file is running offline, and whether it has ever been synced before. If not, it will prompt the user to do the initial sync. In addition, the MirrorSync setup script sets the $$MIRRORSYNC_CLIENTID global variable, which is necessary for some primary key strategies ([[#Primary key / serial numbers |see the Primary Key section above]]).<br />
<br />
Remember that the MirrorSync script is a regular FileMaker script that can be set to run at any time by the developer. For example, if there is a critical section of your application that requires users to see what the latest value is before they make a change, trigger the sync when the user navigates to that screen, and again when they are finished editing in that screen. You could make it so that checking a box, clicking a button, or any other condition that you choose can trigger the sync to happen.<br />
<br />
====Can MirrorSync run automatically every x seconds/minutes?====<br />
Yes, you can use an On Timer script to trigger this. However, keep in mind that when the script runs, it commits the current record and pops open a new window that could be open for a few seconds or longer. This could get annoying if it happens in the middle of something that the user is working on. For this reason, we recommend the approach in the previous question of linking your script sync operations to some user-initiated action. The exception to this is unattended computers - if you want to have a computer that is running MirrorSync all the time for purposes of having an extra copy of the database replicated, without a user working on it, then by all means go ahead and use an On Timer script step (and be sure to see [[#I don't want users to see any dialogs when the sync runs, can I prevent them from showing?|the FAQ above about]] disabling dialogs).<br />
<br />
==== Customizing the MirrorSync layout ====<br />
Feel free to make cosmetic changes to the 'MirrorSync' layout that is pasted into your solution. However, follow these tips before making changes:<br />
* Make sure you are able to successfully sync on FileMaker Pro and FileMaker Go before making customizations.<br />
* Make a backup copy of the unmodified MirrorSync layout first.<br />
* It is important that you preserve the tabs on the layout, and that the same fields remain in those tabs. The other thing to be careful about is that there are two 1x1 pixel web viewers on the MirrorSync layout. Make sure that those remain visible on the layout.<br />
* If the sync stops working after you make the changes, then you may have inadvertently lost the web viewers on the layout. Restore them from the backup copy of the layout.<br />
<br />
=== Licensing ===<br />
<br />
==== How does licensing and pricing work for MirrorSync? ====<br />
MirrorSync is completely free to use, with no limitations on features, for syncing FileMaker Server with a single copy of FileMaker Pro or FileMaker Go. You can optionally purchase additional server configurations or devices.<br />
<br />
The supported configuration types are:<br />
* FileMaker Server with FileMaker clients (Go or Pro)<br />
* FileMaker Server with FileMaker Server<br />
* FileMaker Server with any SQL database (Oracle, MySQL, and MS SQL Server are fully supported. You may also sync with any database with a JDBC driver).<br />
* SQL database with SQL database<br />
* SQL database with FileMaker clients (Go or Pro)<br />
<br />
Devices are sold in quantities of 1, 5, 10, 40, and unlimited. These can be purchased in addition to the single device that comes with MirrorSync for free.<br />
<br />
==== Is MirrorSync included in the 360Works Portfolio Bundle?====<br />
Yes. MirrorSync 2 is free for one device, but Portfolio Bundle (http://360works.com/portfolio) subscribers will receive an additional 10 device pack (for a total of 11 devices). Server-to-server configurations are not included in the Portfolio License, and must be purchased separately. There is also a special licensing program for FileMaker Business Alliance (FBA) members; contact us at support@360works.com for details.<br />
<br />
==== Is there a vertical market license type for MirrorSync? ====<br />
Yes. Contact support@360works.com for details about how this works.<br />
<br />
=== Miscellaneous questions ===<br />
<br />
====Is MirrorSync localized into any non-English languages? Does it work in other languages?====<br />
At this time, MirrorSync is only localized to English. Our current focus is on adding features, but we anticipate translating this into other languages when the product is more mature. If you would like to offer help with translation, please contact support@360works.com to let us know. You should still be able to add MirrorSync to your solution in other languages. See the previous section on customizing dialogs for tips on localizing your solution.<br />
<br />
====I only have an offline copy of my file left, and need to upload it back to the server. What do I do?====<br />
If necessary, you can re-upload an offline copy of the file to FileMaker Server and use it with MirrorSync. <b>Be sure to remove the "Client" record in the MirrorSync table</b>, and keep only the "Server" record. To do this, navigate to the MirrorSync layout, switch to the Debugging tab, and perform a find for "Server" in the type field. Select the inverse of the records found by pressing the pie icon in the status bar. Then, delete those other records.<br />
<br />
=== Troubleshooting/Known Issues ===<br />
<br />
==== The maximum number of users are currently using this copy of FileMaker Pro====<br />
<br />
[[File:MirrorSyncLicense.png|thumb|Example of error message]]<br />
<br />
There is a bug in FileMaker Pro and FileMaker Pro Advanced that may occur when pasting the MirrorSync script, or editing the MirrorSync script. This occurs due to the references found in the script, which will reference both the internal and external IP address. FileMaker then opens both of those references, which triggers the licensing server as two copies of FileMaker Pro. This error would occur for any script that contains both references to a single hosted file. <br />
<br />
There are two work arounds for this:<br />
<br />
# Upgrade your single user license to a volume license. You can contact FileMaker directly to upgrade your license if you have 5 or more copies.<br />
# Paste the script and let FileMaker close due the licensing error. The script will save appropriately, and should work correctly.<br />
<br />
If you require assistance on this issue, please let us know.<br />
<br />
====I keep getting a 102 'Field is missing' error, but I know my Sync layouts have all the right fields, what's wrong with it?====<br />
Make sure that the sync layouts are matching in both the offline and server copy. If you have repeating fields, make sure the fields show the maximum number of repetitions that are defined in the field definitions. In other words, if a field can repeat 5 times, make sure the repetitions in the inspector show 5.<br />
<br />
====Sync fails every time with error: Last sync failed: java.sql.SQLException: Error in table <Sync Layout Name>: Parse Error During Update 1: -1====<br />
This issue arises if a syncing solution has more than 998 syncing fields. The limit for the number of variables Filemaker will allow in a Let statement is 1000. During our Server <-> Client transactions, we require two variables for internal use, so the maximum syncing field limit per table is 998.</div>Sarahhttp://docs.360works.com/index.php/First_Data_E4First Data E42014-01-14T20:25:10Z<p>Sarah: Created E4 Page</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==First Data E4==<br />
<br />
First Data E4 can process a wide variety of transactions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account with [https://globalgatewaye4.firstdata.com/ First Data E4], and you'll need to get your Gateway ID and your eCommerce terminal password. Log in to your account, and choose Administration at the top. Navigate to the terminals tab, and click on the eCommerce terminal. You can then view your gateway ID and generate a password. Use these as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of gateway ID and password. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
gatewayID;<br />
password; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. If you have a card present account, pass in cardPresent=true.<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("E4"; "cardPresent=true")]</pre><br />
<br />
'''Returns''': 1 if a valid gateway is provided, ERROR otherwise.<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
Once you properly configure your merchant account, you can quickly and easily process payment transactions.<br />
<br />
You must provide the following information for a credit card payment transaction:<br />
* merchant account name (this might also be known as a store id)<br />
* transaction key (this might also be known as a password or token)<br />
* dollar amount<br />
* credit card number<br />
* credit card expiration date<br />
* card holder's first name<br />
* card holder's last name<br />
<br />
The CCProcessPayment function will process a transaction and return a transaction ID. This function returns a transaction ID if the transaction is successful or the word ERROR if the transaction fails. For detailed information about the most recent transaction failure, call the CCLastError function before calling any other transaction-processing function.<br />
<br />
In your script, you would then have a second line after setting the gateway.<br />
<br />
Set Variable [$result Value: <br />
CCProcessPayment(<br />
gatewayID, <br />
password;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"firstName=" & Payment::First;<br />
"lastName=" & Payment::Last;)]<br />
<br />
'''Returns''': a verification code from the payment gateway service if the order is successful, or "ERROR" if there was a problem<br />
<br />
'''Note''': It is important to store the resulting transaction ID because you may need it later to void the transaction, issue a refund or capture a previously authorized transaction.<br />
<br />
You may submit optional parameters to most of Plastic's payment-transaction processing functions. These parameters will be submitted to the payment gateway along with the basic transaction information. Although they are not usually required to process an order, these parameters can be useful for tasks such as address verification or linking a transaction to a customer id or an invoice number. To supply additional parameters to a function call, add them to the end of the parameter list after the last required parameter, using a "key=value" syntax.<br />
<br />
Set Variable [$result Value:<br />
CCProcessPayment(<br />
gatewayID, <br />
password;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"firstName=" & Payment::First;<br />
"lastName=" & Payment::Last;<br />
"chargeDescription=" & Payment::description;<br />
"verificationCode=" & $securityCode)]<br />
<br />
{{Template:E4 Optional Parameters}}<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
A sale transaction for credit card contains two parts: an authorization which verifies and places a hold for the amount, and a capture, which actually transfers the funds.<br />
To run an authorization, pass in an additional parameter authMode=AUTH_ONLY.<br />
<br />
Set Variable [$result Value:<br />
CCProcessPayment(<br />
gatewayID,<br />
password;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"firstName=" & Payment::First;<br />
"lastName=" & Payment::Last;<br />
authMode=AUTH_ONLY)]<br />
<br />
'''Returns''': a verification code from the payment gateway service if the order is successful, or "ERROR" if there was a problem<br />
<br />
After running an authorization, run the appropriate '''CCProcessAuthorizedPayment'''. Pass in the previousTransactionId from the transaction ID you received from the process with authMode.<br />
<br />
{{Template:E4 Optional Parameters}}<br />
<br />
<pre>Set Variable $result Value:<br />
CCProcessAuthorizedPayment(<br />
gatewayID,<br />
password;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre><br />
<br />
The dollarAmount is not required to process the authorized payment.<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
gatewayID;<br />
password;<br />
chargeAmount;<br />
"";<br />
"";<br />
"swipe=%B1234123412341234^LAST/FIRSTM^1112101000000000011100111000000?;1234123412341234=11121010000000000111?";<br />
"firstName=" & Payment::First;<br />
"lastName=" & Payment::Last;)]<br />
</pre><br />
<br />
=== Voiding Transactions ===<br />
<br />
Variable [$result; Value:<br />
CCVoidPayment (<br />
gatewayID ;<br />
password ;<br />
previousTransactionID;<br />
amount=refundAmount)]<br />
<br />
Voids a previously processed payment. The previousTransactionID should be the transaction ID of the transaction you wish to void. This value is returned by the CCProcessPayment function. Alternately, you can use the CCLastPaymentTransactionID function to get the transactionID of the last processed payment.<br />
<br />
Note that CCVoidPayment will only work on orders that have not settled yet, which means that it will generally only work on payments made that same day. To void settled orders, use CCRefund instead.<br />
<br />
'''Returns''': the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem<br />
<br />
See also: CCLastPaymentTransactionID: the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem (use CCLastError for more detailed information about the nature of the error).<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|gatewayID|password}}<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/Template:E4_Optional_ParametersTemplate:E4 Optional Parameters2014-01-14T20:07:47Z<p>Sarah: Created page with "<center><big>Click Expand to see the list of optional parameters:</big> {| class="wikitable mw-collapsible mw-collapsed" ! Parameter ! Description |- |verificationCode |the ..."</p>
<hr />
<div><center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|verificationCode <br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|-<br />
|referenceNumber<br />
|an arbitrary reference number for your records <br />
|}<br />
</center></div>Sarahhttp://docs.360works.com/index.php/MirrorSync_2_basic_setupMirrorSync 2 basic setup2013-12-11T20:08:10Z<p>Sarah: /* Three ways to get started with MirrorSync */</p>
<hr />
<div><br />
==Overview==<br />
MirrorSync is an elegant synchronization product that can sync between any combination of FileMaker Pro, FileMaker Go, FileMaker Server, or SQL database (MySQL, Oracle, SQL Server, or any database that supports JDBC). For mobile devices, users can sync the hosted file with their FMGo or Pro clients, go off network to make changes, and sync again when a connection is available. For servers, MirrorSync allows a database to run in multiple locations, or to integrate different databases and make sure that changes to each server are reflected in the other server.<br />
<br />
MirrorSync is only installed on the server computer. It is not a plug-in, and does not require any software installation on client devices.<br />
<br />
MirrorSync is extremely easy to set up. The only changes you will need to make to your database are:<br />
# Enabling the FMXML extended privilege in your security configuration.<br />
# Making sure that every table you want to sync has a primary key, modification timestamp, and creation timestamp.<br />
# Creating a layout for each table.<br />
# Four copy and paste operations.<br />
<br />
==Why use MirrorSync?==<br />
# For mobile users who access the database with FileMaker Go on their iOS device, MirrorSync allows these users to work efficiently with limited or no connectivity to the server network. Each user can take a local copy on their iPad or iPhone, input the information from the field, and then sync when they regain a network connection. Depending on their workflow, they could even specify a one-way sync where their information is pushed to the server, but no data is pulled down, or vice versa for users who need fast read-only information.<br />
# For remote users who work on laptops, MirrorSync solves the problem of how to work productively on a hosted FileMaker database, regardless of network speed. If, for example, you have multiple users connecting to FileMaker Server over a wide area network (WAN) you could notice a substantial slowdown, as every change is immediately written back to FileMaker Server. MirrorSync allows each user to take a local copy of the database which would run on the users machine and not be affected by the WAN performance. The user could sync when they first came into the office, work on their local copy throughout the day, and sync at specified times (or on demand) to push and pull the latest data to the server.<br />
# For groups of users at multiple locations, MirrorSync should be used in server-to-server mode, where an identical copy of the database is installed on FileMaker Server in each location. Each workgroup works at full LAN speed on their own FileMaker Server, and MirrorSync takes care of keeping the servers in sync with each other, so that each workgroup can see and edit changes made by the other group. In this configuration, MirrorSync should be set to sync very often, such as every 30-60 seconds.<br />
# For integration with non-FileMaker databases, MirrorSync is the simplest and most efficient way to accomplish this. For instance, if you have an online storefront running with MySQL or Oracle at a remote data center, but you need to have instant access to all of the orders in a database running on FileMaker Server, MirrorSync can selectively sync certain SQL tables to FileMaker, even if the table and field names do not match. In this configuration, MirrorSync should be set to sync fairly often, such as every 5-10 minutes.<br />
<br />
<br />
<br />
== Requirements ==<br />
* Server:<br />
** Windows 2003r2 or later, or Mac OS X 10.5 or later<br />
** FileMaker Server 11.0v3, 12, or 13, with XML Web Publishing enabled.<br />
** 3 gigabytes or more of RAM. 8 gigabytes or more are recommended for large databases with hundreds of thousands of rows, or for more than 10 simultaneous sync operations.<br />
* Configuration utility (only run by developer / administrator):<br />
** OS X 10.6 or later, or Windows 2007 with Java 1.6 or higher installed<br />
** FileMaker Pro 11, 12, or 13 (FileMaker Pro Advanced is recommended and reduces setup steps, but not required. If you do not have FileMaker Pro Advanced, read [[MirrorSync_advanced_topics#Configuration_without_FileMaker_Pro_Advanced|the FAQ on Is FileMaker Pro Advanced necessary for configuration?]]. Configure MirrorSync using the FileMaker Pro version the FileMaker Server is using- ie, use FileMaker 12 for FileMaker 12 Server for the initial configuration.<br />
* Sync Client:<br />
** Mac or Windows with FileMaker Pro 11, 12, or 13 OR<br />
** FileMaker Go (any version) running on iPad, iPhone, or iPod Touch<br />
<br />
==MirrorSync With Hosting Providers==<br />
<br />
MirrorSync supports hosting provider installations of MirrorSync.<br />
<br />
The following companies have indicated that they are set up or willing to configure their servers to host MirrorSync. If you'd like to be added to this list, please contact us at plugins@360works.com.<br />
<br />
* '''ODI Technologies''' ( http://www.oditech.com/ )<br />
* '''Michael Tinder, DataUp365''' ( http://dataup365.com/DU/ )<br />
* '''John May, Point in Space''' ( http://www.pointinspace.com/ )<br />
* '''Andrew McCallum, Niche IT Pty Lty''' ( http://www.nicheit.com.au/ )<br />
* '''Foxtail Technology''' ( http://www.foxtailtech.com/ )<br />
* '''NeoCode Software''' ( http://www.neocodesoftware.com )<br />
* '''WorldCloud''' ( http://www.worldcloud.com )<br />
* 360Works can also host your database with MirrorSync, so [mailto:infobox@360works.com please contact us directly] about this service.<br />
<br />
If you are a hosting provider, read the [[MirrorSync_advanced_topics#Installation_for_hosting_providers | Installation for hosting providers]]' section in the advanced documentation page.<br />
<br />
==Technical overview==<br />
MirrorSync is a web application, installed on a server (typically on FileMaker Server) and accessed on client machines through a FileMaker Web Viewer and the Insert from URL script step. MirrorSync communicates with FileMaker Server using the XML Web Publishing Engine.<br />
<br />
For FileMaker Pro/Go sync, users run the sync by triggering a regular FileMaker Script in the solution. For server-to-server sync, the syncs are run using the MirrorSync admin utility, and can be scheduled to run in the background at regular intervals.<br />
<br />
There are no plug-ins or other software to install on user's devices. Java is not a requirement except for the server and for the developer configuration.<br />
<br />
For server-to-server sync, all communication is done via the XML Web Publishing Engine, or via JDBC (for non-FileMaker databases).<br />
<br />
== Three ways to get started with MirrorSync ==<br />
We've setup three ways for you to try MirrorSync:<br />
# <b>Live demo (time to sync: Less than 1 minute)</b>: If you would like to see MirrorSync in action without even needing to install anything, you can download our live MirrorSync demo database from [http://sync.360works.com/MirrorSync/dbDownload/4c43e3e3-becd-4239-83cf-80dda86993c6 here]. Just open the file in FileMaker Pro or Go, make some changes, and then hit the sync button. To see how MirrorSync works between multiple devices, use that same download URL on a different device and sync away! Be aware that the data in this file is shared with everybody who downloads it, and also that it resets every night at midnight EST, so don't put anything important in this file.<br />
# <b>Sync using the Tasks template (time to sync: Approximately 20 minutes)</b>: Using the tasks starter solution that comes with FileMaker Pro, we provide a step-by-step video walkthrough that you can follow along with. This 13 minute video starts with creating a new FileMaker database and goes through setup and sync. Just watch the video for each step, and pause while you do it on your own file. [http://www.youtube.com/watch?v=quqy-aXQ2xA&feature=youtu.be Watch the video on YouTube].<br />
# <b>Configure your own file for syncing (time to sync: 30-90 minutes for most solutions)</b>: Follow the instructions below to configure MirrorSync with your own FileMaker solution.<br />
<br />
== Installing / upgrading ==<br />
MirrorSync has a standard OS X and Windows installer included with it. Just double-click the installer for your platform and follow the instructions. Be aware that if you re-install FileMaker Server at some point in the future, you may need to re-run the MirrorSync installer in order to set the web server settings correctly.<br />
<br />
If you are upgrading from MirrorSync 1, be aware that existing configurations will not be preserved, and must be re-created. Offline users will not be able to sync with their old offline files, so they should sync any unsaved changes before proceeding. Your existing sync layouts can still be used with MirrorSync 2, with one change: You must include a creation timestamp field on the layout, in addition to the required fields for version 1. Read the [[MirrorSync_advanced_topics#upgradeFrom1|upgrading section]] in the advanced documentation for more details.<br />
<br />
== Preparing your database for use with MirrorSync ==<br />
<div id="multifile"></div><br />
* MirrorSync only supports sync with a single-file database, so if you have a multi-file solution (ie. separation model or migrated from older FileMaker version), make sure that there is a single main file with external table occurrences referencing the other files. When you distribute offline files to your users, you will distribute the entire set of files, which will include the main sync file.<br />
<div id="XMLpriv"></div><br />
* Be sure that the XML extended privilege is enabled in FileMaker Pro for all accounts that will use MirrorSync. Choose this option under File > Manage > Security… Double click the FileMaker user, and choose Edit… from the Privilege Set.<br />
<div id="primarykey"></div><br />
* Make sure that every table in your solution has a primary key. This is a unique identifier which cannot be empty, and should never be changed once the record is created. MirrorSync can work with traditional serial number primary keys, UUID primary keys, or custom primary key strategies. It will save steps during setup (but it's not required) for your primary keys to have the 'not empty' validation option enabled. Also, if you are using UUID primary keys, be sure to <b>UNCHECK</b> the field options checkboxes that say 'Do not replace existing value of field' and 'Prohibit modification of value during data entry'. For a deeper discussion of how primary keys are handled when syncing, refer to '[[MirrorSync_advanced_topics#Primary_key_.2F_serial_numbers|Primary key considerations]]' in the advanced documentation.<br />
* If your solution uses serial numbers as user-visible data for things like job numbers, check numbers, P.O. numbers, or invoice numbers, refer to the section '[[MirrorSync_advanced_topics#What_if_I_need_to_assign_a_user-friendly_serial_number_to_my_records_that_stays_the_same_when_it_is_synced.3F_For_example.2C_an_invoice_number.3F|User-visible serial numbers]]' in the advanced documentation.<br />
<div id="timestamps"></div><br />
* Every table (including join tables) must have a timestamp field which is set to auto-enter a modification timestamp, as well as a creation timestamp field which auto-enters the creation timestamp. If you will have users with direct, online access to FileMaker Server who are <i>not in the same time zone as the FileMaker Server</i>, you will need to set up special host modification timestamps as outlined in the '[[MirrorSync_advanced_topics#Does_MirrorSync_work_with_timezones.3F |Time zone considerations']] section of the advanced documentation. This requirement does not apply to offline users in different time zones, who access the server via MirrorSync.<br />
* Please remove or rename fields that have parentheses ( ) or square brackets [ ] in the name. These fields are incompatible with MirrorSync.<br />
* Host the database on FileMaker Server. Open the file from the server with FileMaker Pro Advanced, using a full access account. If you do not have FileMaker Pro Advanced, refer to the '[[MirrorSync_advanced_topics#Configuration_without_FileMaker_Pro_Advanced|Configuration without FileMaker Pro Advanced']] section in the advanced documentation.<br />
<br />
== Integrating MirrorSync into your solution ==<br />
<div id="install"></div><br />
Here are the steps to integrate MirrorSync into your solution:<br />
# Install MirrorSync. You can install MirrorSync anywhere, although the easiest option is to install it on your FileMaker Server. During installation, you will create a username and password that will be used to administer MirrorSync.<br />
# After installation, you will be taken to the MirrorSync home page. This is located at http://yourServerAddress/MirrorSync, or in some cases, http://yourServerAddress:42424/MirrorSync. Keep in mind that you can open this page and proceed with the rest of the integration process from your own computer - you don't need to do the entire process from where you have MirrorSync installed. From the home page, click the blue 'Launch MirrorSync Client' button. If you are using Mac OS X, you will then need to double-click the downloaded JNLP file.<br />
# Use the username and password you created during setup to log in to the config client, and then follow the setup instructions in the config client.<br />
# After completing the setup, if you will be syncing with FileMaker Pro or Go, you will need to distribute offline copies of your solution to your users. Click the 'Download Database' button in the config client and choose either 'Download' for quick testing on your own computer, or 'Create Link' for deployment to end users.<br />
# Once you have created an offline copy, run the 'MirrorSync' script to do the initial sync, and then run it again whenever you want to sync with the server. If you'd like to, you can add a button somewhere on the layout for users to run the sync easily.<br />
<br />
== Distributing new versions of your application ==<br />
When you make development changes to the file hosted on FileMaker Server, as long as you do not delete or rename fields, it will not interfere with offline user's ability to sync. You can add new tables, layouts, fields, scripts, etc., and your existing offline files will continue to sync normally.<br />
<br />
Once you are ready to deploy your changes to offline users, edit the configuration in the MirrorSync admin utility. When you get to the end of the process, re-copy and paste the script steps into your FileMaker solutions. Send an e-mail to your users with a download link (you can use one you've generated in the past or create a new one) and instructions to sync their old file, delete it, and then download a new one. Users who do not download the file will also continue to sync normally, they just won't have the latest and greatest version of the solution.<br />
<br />
== Advanced topics ==<br />
This document should get you up and running with MirrorSync. However, there are many advanced features and customizations available, which are covered on the [[MirrorSync advanced topics]] page.<br />
<br />
== Getting help ==<br />
If you encounter an unexpected error message when syncing, please go to the MirrorSync homepage and click the link titled 'report a bug'. This will send us the sync log file, which is required to solve almost all issues. Be sure to include your contact info in the bug report so that we can get in touch with you.<br />
<br />
There is an [http://fmforums.com/forum/forum/172-mirrorsync-by-360works/ online discussion forum] hosted by FMForums. Please look through the posts and see if your question has been posted before making a new topic.<br />
<br />
If you have other questions, we have a dedicated support team that is ready to help. Send us an e-mail at support@360works.com or call us at 866-662-9185.</div>Sarahhttp://docs.360works.com/index.php/MirrorSync_1MirrorSync 12013-12-11T19:20:42Z<p>Sarah: Created page with "{{TOC limit}} ==Overview== MirrorSync is a simple, elegant FileMaker synchronization product that connects FileMaker Server with FileMaker Pro and FileMaker Go. Users can syn..."</p>
<hr />
<div>{{TOC limit}}<br />
<br />
==Overview==<br />
MirrorSync is a simple, elegant FileMaker synchronization product that connects FileMaker Server with FileMaker Pro and FileMaker Go. Users can sync the hosted file with their FMGo or Pro clients, go off network to make changes, and sync again when a connection is available.<br />
<br />
==Why use MirrorSync?==<br />
MirrorSync is designed to solve the problem of how to work productively on a hosted FileMaker database without being tied to FileMaker Server. If, for example, you have multiple users connecting to FileMaker Server over a wide area network (WAN) you could notice a substantial slowdown, as every change is immediately written back to FileMaker Server. MirrorSync allows each user to take a local copy of the database which would run on the users machine and not be affected by the WAN performance. The user could sync when they first came into the office, work on their local copy throughout the day, and sync at specified times (or on demand) to push and pull the latest data to the server.<br />
<br />
Another use case would be users who work in the field and may have limited or no connectivity to the FileMaker server network. The user could take a local copy on their iPad or iPhone, input the information from the field, and then sync when they regain a network connection. If the connection is spotty, they could even specify a one-way sync where their information is pushed to the server, but no data is pulled down, thus speeding up the process.<br />
<br />
== Requirements ==<br />
<br />
{{ mbox | text = Please note that the latest Java 1.6 Update for Mac OS X Lion or higher breaks Java Web Start Functionality. For instructions on how to resolve this issue, [http://www.youtube.com/watch?v=AcZMla7u0jc&hd=1 click here].}}<br />
<br />
* Server:<br />
** Windows 2003r2 or later, or Mac OS X 10.5 or later<br />
** FileMaker Server 11.0v3 or 12.<br />
* Configuration utility:<br />
** OS X 10.6 or later, or Windows 2007 with Java 1.6 or higher installed<br />
** FileMaker Pro 11 or 12 (FileMaker Pro Advanced is recommended and reduces setup steps, but not required. If you do not have FileMaker Pro Advanced, read [[#Q:_Is_FileMaker_Pro_Advanced_completely_necessary_for_configuration?|the FAQ on Is FileMaker Pro Advanced necessary for configuration?]]<br />
** NOTE: This is only required for one machine on the network<br />
* Sync Client:<br />
** Mac or Windows with FileMaker Pro 11 or 12 OR<br />
** FileMaker Go running on iPad, iPhone, or iPod Touch<br />
<br />
==MirrorSync With Hosting Providers==<br />
<br />
As of 1.25, MirrorSync supports hosting provider installations of MirrorSync.<br />
<br />
The following companies have indicated that they are set up or willing to configure their servers to host MirrorSync. If you'd like to be added to this list, please contact us at plugins@360works.com.<br />
<br />
* '''ODI Technologies''' ( http://www.oditech.com/ )<br />
* '''Michael Tinder, DataUp365''' ( http://dataup365.com/DU/ )<br />
* '''John May, Point in Space''' ( http://www.pointinspace.com/ )<br />
* '''Andrew McCallum, Niche IT Pty Lty''' ( http://www.nicheit.com.au/ )<br />
* '''Foxtail Technology''' ( http://www.foxtailtech.com/ )<br />
*'''NeoCode Software''' ( http://www.neocodesoftware.com )<br />
* 360Works can also host your database with MirrorSync, so [mailto:infobox@360works.com please contact us directly] about this service.<br />
<br />
To install multiple instances of MirrorSync, choose either the Hosting provider option on Mac, or hold down ALT on a Windows computer. This will allow you to name a new instance of MirrorSync and install multiple copies. These copies can then be managed via the 360Admin utility, which is found either in your Program Files or Applications folder. When installing additional instances of the application, only a single Tomcat process will be installed which is shared by all of the MirrorSync instances.<br />
<br />
We strongly recommend you use the installer, even for hosting providers. We at 360Works use the installer for our hosting clients as well, and find it easy to update and manage. If you are curious as to what the installer actually does, it modifies and adds the following:<br />
<br />
* Creates a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows that is readable and writeable.<br />
* Downloads and installs an instance of [http://tomcat.apache.org/download-60.cgi Tomcat 6] into that folder. (Only one copy of Tomcat is installed, regardless of how many copies of MirrorSync are running)<br />
* Copies the installer's MirrorSync.war which deploys the web app, as well as the other supporting material into the folder.<br />
* Adds a launch daemon in Library/LaunchDaemons in OS X, or creates a Windows Service to automatically start Tomcat.<br />
* Modifies the http.conf file for Apache to allow for URL redirection. If using Windows with IIS, we create an ISAPI filter for the URL redirect.<br />
* Copies a lightweight Admin Utility JAR file to manage Tomcat to either Program Files/360Works or Applications.<br />
<br />
If upgrading from an older version of MirrorSync, we'll copy over the SyncData and remove the URL redirects for the old MirrorSync. <br />
<br />
If you prefer MirrorSync to be deployed to your own instance of Tomcat that you've set up, please note and follow these instructions:<br />
<br />
# Create a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows. Make sure that it is readable and writeable to the process that Tomcat is running as.<br />
# Rename the MirrorSync.war file to whatever name you'd like the instance to run as for your hosting customer, ie. 'CustomerXSync.war'<br />
# Drop that file into the webapps directory in your Tomcat instance.<br />
# Modify the the MirrorSync.xml context descriptor and set the administrative username and password for MirrorSync. In Tomcat 6, this file is automatically written to the Tomcat/conf/Catalina/localhost. If you are running Tomcat 7, the file is located in the webapps/MirrorSync/META-INF/context.xml file, or you can follow the instructions at http://tomcat.apache.org/tomcat-7.0-doc/config/host.html regarding copyXML to get the same behavior as Tomcat 6 (we recommend doing this, so that you don't lose the context.xml file every time the application is redeployed).<br />
# If necessary for your configuration, set up URL forwarding from IIS / Apache to your Tomcat connectors. [http://tomcat.apache.org/tomcat-6.0-doc/index.html See tomcat documentation on how to do this].<br />
<br />
==Important MirrorSync Information==<br />
Before moving further in MirrorSync, there are a few important points you need to know about. MirrorSync is a web application, accessed on client machines through a FileMaker Web Viewer. MirrorSync communicates to FileMaker Web Publishing Engine using XML to push and pull data to FileMaker Server. To configure and run MirrorSync, follow the instructions in the configuration utility to modify the hosted copy of the database you wish to sync. User will then download local copies of the hosted database and run the MirrorSync script to sync the local copy to their devices and the server.<br />
<br />
Distributing files is easy. You can either download a copy of the file from FileMaker Server, or MirrorSync, or create a download link. The download link is available to users of version 1.5 and above, and can create a revocable link to download a copy directly to a mobile device or computer. Click Download Database, and choose Create Link. Once you've downloaded the local database, you can make copies of this file, email the file, and use DropBox to distribute the offline copy to other users, iPads, and iPhones. '''When distributing copies, MAKE SURE to not run the sync script in the database!''' Once the sync script is run for the first time, the database is linked to your device's MAC address. Using a previously synced file on devices with different MAC addresses will result in errors. To get a copy of the file that is not linked to any device, simply navigate to your MirrorSync server address, login to the main screen, and choose "Download Database". You'll download a new copy that you can then email to other devices. You can also simply revisit the download link provided.<br />
<br />
'''After distribution, it is very important that you run the MirrorSync script before making any changes.''' This links the local copy to your device and ensures that you have the most recent information from the hosted database. During the initial sync, information from the hosted database takes precedence, so any changes you've made will be reverted.<br />
<br />
Devices cannot sync simultaneously. If a user gets a "Sync in Progress" message, they will need to try again in a few seconds to allow the first sync to finish.<br />
<br />
== Preparing your database for use with MirrorSync ==<br />
<br />
MirrorSync only supports sync with a single-file database, so if you have multiple files, create a new table with external table references to the other files.<br />
<br />
Be sure that XML extended privilege is enabled in FileMaker Pro. Choose this option under File > Manage > Security… Double click the FileMaker user, and choose Edit… from the Privilege Set.<br />
<br />
http://demo.360works.com/wiki/image002.png<br />
<br />
Make sure the Access via XML Web Publishing option is enabled and has a checkmark. Please note that this screen is different in FileMaker 12.<br />
<br />
Most tables that you would like to synchronize need to have a unique identifier, also known as a primary key. This can either be a sequential serial number, a universally unique identifier (UUID) generated with the new FileMaker 12 Get(UUID) function, or any other value that is guaranteed to be unique, non-empty, and unchanging for every record. If you are using UUID primary keys, it is important that you do NOT check the box prohibiting modification of these values -- for serial numbers this is irrelevant and syncs will work either way. The exception for this requirement is many-to-many join tables, which often do not have a primary key, and instead have two foreign keys linking them to primary keys in other tables. It is OK if these tables do not have primary keys.<br />
<br />
Every table (including join tables) must have a timestamp field which is set to auto-enter a modification timestamp.<br />
<br />
You should create a new layout for each table that you plan on synchronizing. Be sure to include the modification timestamp, primary key, and any fields that you want to synchronize. Be sure to NOT include summary fields, global fields, and unstored calculations. These will make synchronization slower. These are easy to spot, because if you enable the 'View->Show->Quick Find' menu in FileMaker, those field types will either have a yellow magnifying glass, or no magnifying glass. Remove those fields from the layout, and keep the ones with the green magnifying glass.<br />
<br />
http://demo.360works.com/wiki/greenglass.png<br />
<br />
MirrorSync checks with the initial sync which fields are read or writeable. If you have options selected that may prohibit writing to a field, MirrorSync may not be able to sync those fields appropriately. These options include "Prohibit modification of value during data entry" and "Validated by Calculation" under the options section for a field.<br />
<br />
Please remove or rename fields that have parentheses ( ) or square brackets [ ] . These fields are incompatible with MirrorSync. <br />
<br />
Host the database on FileMaker Server. Open the file as a guest with FileMaker Pro Advanced, using a full access account.<br />
== Configuring MirrorSync without FileMaker Pro Advanced ==<br />
<br />
=== Steps to manually import MirrorSync tables in FileMaker Pro ===<br />
*Locate the XML schema that came with your MirrorSync download.<br />
*Open FileMaker Pro and navigate to File -> Import Records -> XML Data Source.<br />
*In the "Specify XML and XSL Options" window, choose the "File" radio button, then click "Specify...".<br />
*Navigate to your MirrorSync download folder and choose the MirrorSync.xml file from the XML Schema subfolder.<br />
*Click continue to bring up the Import Field Mapping window. <br />
*Open the "Target" drop down menu, and select "New Table ("MirrorSync")"<br />
*Verify that the source fields and target fields have been matched correctly.<br />
*Click import.<br />
<br />
=== Steps to configure your new MirrorSync table ===<br />
*Navigate to File -> Manage -> Database...<br />
*Navigate to the "Fields" tab, highlight the "id" field and click the "Options..." button.<br />
*Check the box next to "Serial Number." Set it to generate on creation.<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the boxes next to "Not Empty" and "Unique Value" then press OK.<br />
*Next, highlight the "modstamp" field and click the "Options..." button.<br />
*Check the box next to "Modification" and ensure that the drop down menu says "Timestamp (Date and Time)."<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the box next to "Not Empty" then press OK<br />
*Finally, highlight the "container" field, and select "Container" from the "Type" drop down menu, next to the "Options..." button.<br />
<br />
You are now finished manually configuring your MirrorSync table. Click the OK button to close the database management window, and return to the MirrorSync configuration. (Be sure to save your changes!)<br />
<br />
<br />
==MirrorSync Quick Start Tutorial: Syncing the Demo File==<br />
MirrorSync comes with a fully featured demo. You may use the demo for your own files, or walk through a sample configuration below. The only demo limitation is that once you have created an offline copy of the database, that particular copy can only sync for 24 hours. You can renew this 24 hour window at any time by downloading a new offline copy from the server.<br />
<br />
MirrorSync ships with two example files: "Contact Management.fp7" and "Contact Management.fp12", along with a MirrorConfig.txt file. These files are copies of the Contact Management Starter Solution from FileMaker Pro 11. The only changes that have been made are the addition of the table generated by the MirrorSync Configuration Utility.<br />
<br />
To use the demo file:<br />
* Host the file on FileMaker Server<br />
* Run the appropriate Mac Installer.app or Windows Installer.jar<br />
* On the client machine, navigate to the URL provided at the end of the installation to download the MirrorSync utility. Be sure to match the capitalization of the word 'MirrorSync' in the URL.<br />
* Run the configuration utility using the username and password you created during installation. From the starting screen, click import and choose the configuration file (MirrorConfig.txt) from your download.<br />
<br />
http://demo.360works.com/wiki/ImportConfiguration.png<br />
<br />
* With the new configuration selected, click "Edit" from the main screen and proceed through the configuration utility. If using a three-machine FileMaker Server deployment, be sure to enter the host name of the web server. Otherwise, use 'localhost'. Be sure the "Contact Management" database that you hosted on FileMaker Server is selected, then click "Next" through the next six configuration screens. On the final screen, copy the scripts, layouts, and steps as indicated.<br />
<br />
http://demo.360works.com/wiki/ScriptStepChange.png<br />
<br />
* Download the file and run the MirrorSync script. This is a local copy of the FileMaker file and is linked with your current machine during the initial sync. To sync this file with multiple devices, follow the steps below for a custom configuration.<br />
<br />
==MirrorSync Setup Tutorial: Custom Configurations==<br />
In this tutorial, we'll walk through a MirrorSync configuration from start to finish, using the Contact Management.fp7 FileMaker Starter Solution. If you are using FileMaker 12 and would like to follow along, you can download a converted file at <br />
http://mirrorsync.360works.com/static/Contact%20Management.zip<br />
<br />
1) Prepare the file. This involves:<br />
- enabling the Access via XML Web Publishing extended privilege set in File > Manage > Security<br />
- ensuring that the database is contained in a single file<br />
- ensuring that each table has a primary key field, either with an auto-entered, unique serial number or UUID<br />
- ensuring that each table has a modification timestamp field, also set to auto-enter<br />
- creating a new "sync" layout for each base table (not table occurrence). The layout should only contain those fields that should be synched. This means no global fields, summary fields, or unstored calculations. If your solution has repeating fields, make sure to show all of the repetitions on the layout.<br />
<br />
2) Host the file on your FileMaker Server and run the MirrorSync installer. If you have a multiple machine deployment, run the installer on the machine where the web publishing engine is running. Make note of the URL at the end of the installation process.<br />
<br />
3) On your client machine, navigate to the MirrorSync URL and launch the MirrorSync Client. Follow the instructions in the configuration utility. This involves setting the primary keys and relationships, choosing the layouts to sync, confirming the fields, and inserting the table, script, and layout that MirrorSync generates. If you get stuck, look for the blue question marks - they have helpful tooltips.<br />
<br />
4) During the final screen of the configuration, MirrorSync will generate a table, script, layout, and script steps for synching. Copy and paste these into the hosted database (if you don't have FileMaker Pro Advanced, you'll need to import the XML for the table). Once these changes are made, click finished.<br />
<br />
5) From the MirrorSync Dashboard, choose the correct configuration and click "Download Database". This will download a copy of the database to your local machine. Keep in mind that after the initial sync this copy is tied to your device. If you would like to have the database on multiple devices, you'll need to navigate to the server address on that device, launch the client, and download the database directly, or download a fresh copy of the database and email it to the device.<br />
<br />
6) Before making any local changes, run the MirrorSync script.<br />
<br />
==Syncing==<br />
<br />
To sync changes to the server copy, simply run the MirrorSync script. This script is attached to the button on the MirrorSync layout, but users may choose to attach it to whatever is required. Be sure to sync once before making changes to assure that both copies are identical.<br />
<br />
Please note: if the database has multiple access accounts with different privilege sets, make a new copy for each user. Do not sync an offline copy of the database to the server using multiple accounts.<br />
<br />
==Main Screen==<br />
<br />
http://demo.360works.com/wiki/mainscreen.png<br />
<br />
After configuration, users can view information about current sync configurations. The left window displays all the current sync configurations. Users may Add new sync configurations, edit existing ones, duplicate, or delete them. If a sync with MirrorSync has been set up on another server, that configuration may be imported using the Import button.<br />
<br />
If a sync configuration needs to be changed, there are a couple of things to keep in mind. Choose Edit… from the Main Screen and walk through the configuration again. After making the changes required, be sure to delete everything in the MirrorSync script '''first''' and then paste in the new script steps. After walking through the configuration utility, make a fresh copy of the database and run the MirrorSync script again.<br />
<br />
The right window displays information about the currently selected sync and the option to run the sync script.<br />
<br />
The bottom window displays the log for MirrorSync.<br />
<br />
==Updating MirrorSync==<br />
{{ mbox | text = Please note that the updating process is different for hosting providers. [[MirrorSync for Hosting Providers | Please see this page for details.]]}}<br />
<br />
To update MirrorSync to a new version:<br />
<br />
# Download the new version from the website<br />
# Run the installer included in the download on the server<br />
<br />
After installing the new version, users with copies of offline files will be able to continue syncing. Occasionally, the script steps or the table may change in new builds. To check if there are new scripts to run, choose edit from the Main Screen. Keep pressing Next until you get to the final screen, where you copied the layouts, tables, and scripts into the hosted file. If there is an exclamation mark next to a step, hover over it and read the tooltip. You may need to replace the scripts in your solution to take advantage of a new feature, or to solve an issue in an older version.<br />
<br />
Remember, users with older offline files will be able to continue syncing. But to take advantage of the update, simply recopy the elements as directed on the screen and redistribute the offline files. There is no need to delete the configuration.<br />
<br />
If there are issues after upgrading, try restarting the Web Publishing Engine.<br />
<br />
== Frequently Asked Questions ==<br />
===Deployment and installation questions===<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: How_should_MirrorSync_be_installed|How should MirrorSync be installed?]]<br><br />
[[#Q: How do I upgrade MirrorSync to a new version?|How do I upgrade MirrorSync to a new version?]]<br><br />
[[#Q: Are plug-ins required?|Are plug-ins required?]]<br><br />
[[#Q: I had to restart the Web Publishing Engine on FileMaker Server and now the MirrorSync configuration utility is not working! What do I do?|I had to restart the Web Publishing Engine on FileMaker Server and now the MirrorSync configuration utility is not working]]<br><br />
[[#Q: What ports are required for MirrorSync? Can I change them?|What ports are required for MirrorSync? Can I change them?]]<br><br />
[[#Q: Will MirrorSync work on a VPN?|Will MirrorSync work on a VPN?]]<br><br />
[[#Q: Can MirrorSync send encrypted data? What about SSL enabled FMS?|Can MirrorSync send encrypted data? What about SSL enabled FMS?]]<br><br />
[[#Q: I need my database to be HIPPA compliant, what should I do with MIrrorSync?|I need my database to be HIPPA compliant, what should I do with MIrrorSync?]]<br><br />
[[#Q: My solution is behind a firewall. Will MirrorSync still work?|My solution is behind a firewall. Will MirrorSync still work?]]<br><br />
[[#Q: Can MirrorSync sync between two FileMaker Servers?|Can MirrorSync sync between two FileMaker Servers?]]<br><br />
[[#Q: Does MirrorSync work with runtime versions of FileMaker Pro?|Does MirrorSync work with runtime versions of FileMaker Pro?]]<br><br />
[[#Q: I have a three-machine FileMaker Server deployment. How do I install MirrorSync?|I have a three-machine FileMaker Server deployment. How do I install MirrorSync?]]<br><br />
[[#Q: Does MirrorSync support ESS tables?|Does MirrorSync support ESS tables?]]<br><br />
[[#Q: How do I uninstall MirrorSync?|How do I uninstall MirrorSync?]]<br><br />
[[#Q: What if I move servers, change my hostname, or IP?|What if I move servers, change my hostname, or IP?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: How should MirrorSync be installed?====<br />
A: Run either the Mac Installer.pkg or the WindowsInstaller.exe to install the MirrorSync application on the server. Your server can be separate from the Web Publishing Engine, beginning with version 1.5, but must have a Web Server such as IIS or Apache.<br />
<br />
After installation is finished, a message will be displayed pointing to the address where MirrorSync can be configured. Typically the address will display as http://servername/MirrorSync, where servername is replaced with the address of the server. Please keep in mind that the address requires the correct capitalization. From a client computer, navigate to that address to launch the configuration utility.<br />
<br />
====Q: How do I upgrade MirrorSync to a new version?====<br />
To upgrade to a new version, run the new install file (Mac Installer.pkg or WindowsInstaller.exe) and select Upgrade.<br />
<br />
====Q: Are plug-ins required?====<br />
A: No, the only software to install anywhere is the MirrorSync server application, which is installed on the FileMaker Web Publishing Engine. You can send a copy of the FileMaker database to anybody with a copy of FileMaker Pro, and they will be able to run the sync script.<br />
<br />
====Q: Can MirrorSync send encrypted data? What about SSL enabled FMS?====<br />
<br />
A: Yes, it can. To make sure data is encrypted, you'll need a valid SSL certificate installed on the web server where MirrorSync is running. This will ensure that all plain-text data is sent and received encrypted with SSL. To sync container data using SSL, first set up FileMaker server as SSL enabled ([http://www.filemaker.com/downloads/documentation/fm12_security_guide_en.pdf see page 20 of these docs]). After doing so or if FileMaker Server is already is SSL enabled, check the SSL checkbox when configuring MirrorSync. <br />
<br />
If you get an error saying that you have a self-signed certificate, then you will need to follow the [[Custom SSL Certificate setup instructions]].<br />
<br />
====Q: I need my database to be HIPPA compliant, what should I do with MIrrorSync?====<br />
A: HIPPA compliance depends on a large number of requirements. However, one of those requirements is to transmit only encrypted data. See the question above if you experience difficulties. Please keep in mind that encryption is one piece of HIPPA compliance, so consult the [http://www.hhs.gov/ocr/privacy/ Department of Health and Human Services] for more information.<br />
<br />
====Q: What ports are required for MirrorSync? Can I change them?====<br />
MirrorSync transmits container data on port 5003, which is the regular port for communication betwen FileMaker Pro and FileMaker Server. All other field types (text, number, date, time, timestamp) are transmitted using regular HTTP communication, which typically runs on port 80, or port 443 if SSL encryption is being used. These port numbers are set in your web server configuration (IIS on Windows or Apache on OS X), and can be customized to any value you prefer. A good way to test this is to test the FileMaker Web Publishing Engine - if the URL http://yourServer:somePort/fmi/iwp works for you, then it should work for MirrorSync as well.<br />
<br />
====Q: Will MirrorSync work on a VPN?====<br />
Yes. MirrorSync runs over standard HTTP protocols (which are VPN compatible) for non-container data, and standard FileMaker protocols (which are also VPN compatible) for container data.<br />
<br />
====Q: My solution is behind a firewall. Will MirrorSync still work?====<br />
A: MirrorSync communicates with FileMaker Server using a web viewer, so as long as the firewall allows standard HTTP traffic on port 80 (most firewalls are configured to allow this), all of your sync devices should be able to access it through the firewall.<br />
<br />
====Q: Can MirrorSync sync between two FileMaker Servers?====<br />
A: No, MirrorSync depends on web viewers and scripts steps that are only available in regular FileMaker Pro. You can sync between FileMaker Pro and FileMaker Server, but not between FileMaker Server and FileMaker Server. If this feature is important for you, please e-mail us and let us know: plugins@360works.com<br />
<br />
====Q: Does MirrorSync work with runtime versions of FileMaker Pro?====<br />
A: MirrorSync is untested and unsupported for use in this configuration. In addition, the legal licensing agreement for creating runtime versions of FileMaker specifically disallows any automated transfer of data between the runtime version and FileMaker Server. This restriction means that no sync process can legally be used to transfer data between the runtime edition and FileMaker Server, whether that is from a 3rd party or a home-grown automation process. Contact your FileMaker Business Account Manager for volume pricing on FileMaker Pro licenses.<br />
<br />
====Q: I have a three-machine FileMaker Server deployment. How do I install MirrorSync?====<br />
A: While MirrorSync can be installed on whatever machine is most convenient, we recommend that you install MirrorSync in the same location as FileMaker Server, as that will enable the Download Database functionality in MirrorSync. Please keep in mind you can always download the most recent version of the file via the FileMaker Server Admin Console. If that machine does not have a Web Server installed, such as Apache or IIS, your MirrorSync URL will be a direct URL such as http://360works.com:42424/MirrorSync.<br />
<br />
====Q: Does MirrorSync support ESS tables?====<br />
A: Yes! To use MirrorSync with ESS tables, there are additional steps. First, configure MirrorSync in its entirety. You should be able to select your ESS tables and files in the configuration utility. After you have pasted the last script step, download a copy of the file as usual. <br />
<br />
At this point, you need to make some modifications for the file to work offline. Open the downloaded copy, and make the following modifications to the local copy ONLY! Do not run the sync yet.<br />
<br />
* First, delete the data source. This is vital to preventing duplicate records and other artifacts of using ESS. Open File > Manage > External Data Sources and delete the OBDC data source.<br />
* Next, open the File > Manage > Database and navigate to the Tables tab. Copy any ESS tables. Then delete them. Make sure NOT to delete the table occurrences. After all the italicized tables are gone, paste the tables back in. This ensures they are local FileMaker files, not references to external data.<br />
* Make sure the primary keys and modification timestamps are correct. The primary key needs to be an auto-entered serial number or generated UUID.<br />
* Open the relationships tab in the File > Manage > Database and relink any missing tables. <br />
<br />
You can now distribute this file for synchronization to your users. Make a copy of this file and send it to each user who needs a copy. These copies are then ready for synchronization.<br />
<br />
====Q: How do I uninstall MirrorSync?====<br />
A: To uninstall, first stop the Web Publishing Engine. After that, run the original install file (Mac Installer.app or WindowsInstaller.exe) and select Uninstall.<br />
<br />
====Q: What if I move servers, change my hostname, or IP?====<br />
A: To move a MirrorSync installation:<br />
<br />
# First, export your settings by opening MirrorSync and pressing Export for each configuration. This will save each configuration's settings in a simple text file.<br />
# Next, you may uninstall MirrorSync off the server. This will clear the license information and prevent users from syncing to the old server. <br />
# After moving the FileMaker file to the new server, install MirrorSync at the new location and enter your license information. You can them Import your configurations back in.<br />
<br />
'''Please note!''' After moving servers, changing your server's hostname, or IP address, you will need to edit the data sources in the FileMaker file. To do this, open the file on the server and choose File> Manage > External Data Sources and clear out any MirrorSync data sources. Walk through the configurations in MirrorSync again, and repaste the script steps, which will create new data sources with the information provided during setup. Distribute new copies of this correct file to all users, as older versions will not sync.<br />
<br />
You will only need to do this if you need to change the addresses you provided MirrorSync previously. For example, if you made a configuration that pointed to MacMini.local, and never provided an IP address, then there's no reason to walk through this process every time the IP address changed. However, if you specified the internal and external IP addresses in MirrorSync, and those change, this process would be required.<br />
<br />
===Configuration questions===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: I tried to follow the configuration utility, but don't quite understand the process. Do you have a walkthrough somewhere?|I tried to follow the configuration utility, but don't quite understand the process. Do you have a walkthrough somewhere?]]<br><br />
[[#Q: How do I configure synchronization for solutions with multiple database files?|How do I configure synchronization for solutions with multiple database files?]]<br><br />
[[#Q: What happens if I edit my configuration, or make changes to the sync layouts on my hosted database?|What happens if I edit my configuration, or make changes to the sync layouts on my hosted database?]]<br><br />
[[#Q: I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?|I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?]]<br><br />
[[#Q: My external IP addresses are different than my internal IP addresses. What do I need to do?|My external IP addresses are different than my internal IP addresses. What do I need to do?]]<br><br />
[[#Q: Is FileMaker Pro Advanced completely necessary for configuration?|Is FileMaker Pro Advanced completely necessary for configuration?]]<br><br />
[[#Q: I never saw the foreign key mapping screen! What do I do?|I never saw the foreign key mapping screen! What do I do?]]<br><br />
[[#Q: I'm not seeing my databases from the Choose database button. What's happening?|I'm not seeing my databases from the Choose database button. What's happening?]]<br><br />
[[#Q: I keep getting a 102 Field is missing error, but I know my Sync layouts have all the right fields, what's wrong with it?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: I tried to follow the configuration utility, but don't quite understand the process. Do you have a walkthrough somewhere?====<br />
A: There is a [[MirrorSync configuration walkthrough]] page that explains this in more detail.<br />
<br />
====Q: How do I configure synchronization for solutions with multiple database files?====<br />
A: MirrorSync will work fine with multi-file solutions. Whether you're using the separation model, migrated from an older version of FileMaker, or just prefer to split our your tables into separate files, we've got you covered. You will need to select one file as your main file. Make sure that the main file contains table occurrences from the other database files that you want to sync, and when the configuration screen instructs you to create layouts for each table, be sure to create the layouts in the main file.<br />
<br />
When you complete the setup process and get to the step where you click the button to download an offline copy of the database from your server, select the option for a multi-file solution. This will show a checkboxes of all of the database files available on the server. Be sure to select all the database files in your solution.<br />
<br />
====Q: What happens if I edit my configuration, or make changes to the sync layouts on my hosted database?====<br />
A: If you change your configuration or edit your hosted database in a way that affects the sync layouts, then your need to go back through and edit the configuration and re-generate the sync script steps. Delete the current contents of the MirrorSync script and replace with the steps you just downloaded. Then send a copy of this new file to each offline user to replace their database.<br />
<br />
====Q: I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?====<br />
A: After converting your file, you'll need to edit the configuration and replace the MirrorSync script steps with ones generated for the FileMaker 12 file. This is due to the fact that the "Insert from URL" script step doesn't exist in FileMaker Pro 11.<br />
<br />
You'll also need to re-run the MirrorSync installer.<br />
<br />
====Q: Is FileMaker Pro Advanced completely necessary for configuration?====<br />
A: If you do not have a license for FileMaker Pro Advanced, you'll need to import the table data from the XML schema that came with your MirrorSync download.<br />
<br />
Please see [[#Configuring_MirrorSync_without_FileMaker_Pro_Advanced|Configuring MirrorSync without FMP Advanced]] for detailed instructions.<br />
<br />
====Q: I never saw the foreign key mapping screen! What do I do?====<br />
A: If you selected UUIDs as your primary keys at the beginning of the configuration, the foreign key screens will not appear. This is normal and expected behavior. When using serial numbers, primary keys can be (and usually are) re-numbered when they are transferred to another device. MirrorSync needs to know which foreign keys which point to the primary keys, in order to write the new primary key value to each foreign key. When using UUIDs, the primary keys stay the same on every device because there is no possibility of conflict. Therefore, there is never a need to re-write foreign keys.<br />
<br />
====Q: I'm not seeing my databases from the Choose database button. What's happening?====<br />
A: Make sure XML publishing is enabled for the account you are using in MirrorSync. Also be sure the database is accessible from the machine you are installing MirrorSync on.<br />
<br />
Try to navigate to your server's URL, and adding <code>/fmi/xml/FMPXMLRESULT.xml?-dbnames</code> to the end. You should see an XML document listing the databases in FileMaker Server. If you do not, or find a 404 or 401 error, then FileMaker Server may not be configured correctly.<br />
<br />
If there is an authentication required at that test URL, try disabling IIS authentication. FileMaker Server authenticates its password-protected databases; however, this method disables the IIS authentication layer. This will also disable authentication for other websites that are using IIS on that server.<br />
<br />
# From the Control panel, navigate to Administrative Tools > Internet Information Services (IIS) Manager<br />
# Select the website in IIS and choose Action > Properties<br />
# Navigate to the Directory Security pane, and select Edit for authentications. This button may differ in various Windows versions.<br />
# In the Authentications Methods pop up:<br />
#* Make sure Anonymous Access is enabled<br />
#* For Authenticated access, disable the authentication methods.<br />
# Press OK<br />
<br />
====Q: I keep getting a 102 Field is missing error, but I know my Sync layouts have all the right fields, what's wrong with it?====<br />
Please make sure that the sync layouts are matching in both the offline and server copy. If you have repeating fields, make sure the fields show the maximum number of repetitions that are defined in the field definitions. In other words, if a field can repeat 5 times, make sure the repetitions in the inspector show 5. <br />
<br />
<br />
===Sync questions===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: Why can't I transfer my database to another computer after I've synced it?|Q: Why can't I transfer my database to another computer after I've synced it?]]<br><br />
[[#Q: Can I log into my local copy with different accounts/different privilege sets?|Q: Can I log into my local copy with different accounts/different privilege sets?]]<br><br />
[[#Q: Does MirrorSync sync container fields?|Q: Does MirrorSync sync container fields?]]<br><br />
[[#Q: What about SuperContainer? Does MirrorSync work with that?|Q: What about SuperContainer? Does MirrorSync work with that?]]<br><br />
[[#Q: Does MirrorSync sync external container fields?|Q: Does MirrorSync sync external container fields?]]<br><br />
[[#Q: Does MirrorSync do conflict resolution?|Q: Does MirrorSync do conflict resolution?]]<br><br />
[[#Q: Is MirrorSync transactional? What happens if the connection is lost while syncing?|Q: Is MirrorSync transactional? What happens if the connection is lost while syncing?]]<br><br />
[[#Q: Can I use external authentication with MirrorSync?|Q: Can I use external authentication with MirrorSync?]]<br><br />
[[#Q: How do I make changes to my hosted database if I have offline users who are syncing? Can I add fields and tables?|Q: How do I make changes to my hosted database if I have offline users who are syncing? Can I add fields and tables?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: Why can't I transfer my database to another computer after I've synced it?====<br />
A: The MirrorSync server stores information about each device that syncs with it. This includes the primary key, as well as the count of modifications for that record on that particular device. If this file were to be synced from two different devices, this information would conflict and cause problems. If you do try to send a database to another device and sync it, an error message will appear and the sync will be prevented.<br />
<br />
====Q: Can I log into my local copy with different accounts/different privilege sets?====<br />
A: No, you'll need to download a new copy of the database for each of the user accounts you use to the server using multiple accounts with the same file may generate errors.<br />
<br />
====Q: Does MirrorSync sync container fields?====<br />
A:Yes, MirrorSync works with FileMaker container fields as of version 1.1. If container fields are slowing down your synchronization, consider moving containers to a separate table and create new layouts for them. MirrorSync scans for modification timestamps to find records that have been changed, so by moving containers to a separate table with a separate timestamp, they are only uploaded and downloaded when containers change. <br />
<br />
====Q: What about SuperContainer? Does MirrorSync work with that?====<br />
A: Yes, it does. However, with SuperContainer the approach is very different. Only the URLs are synchronized, not the actual files - they remain on the SuperContainer server. The advantage is syncing is very fast - there is no binary data being transferred. The disadvantage is that you'll only have access to the files stored in SuperContainer when you have working network access from your computer or iOS device.<br />
<br />
====Q: Does MirrorSync sync external container fields?====<br />
A: Yes, MirrorSync works with external container fields. If you are using external container fields in FileMaker 12, there are a few steps after configuration that are required.<br />
<br />
#Download a copy of the database from MirrorSync or FileMaker Admin<br />
#Open the copy on a computer, and navigate to File > Save a copy as...<br />
#Under the type drop down, choose "self-contained copy (single file)<br />
<br />
This ensures the copy of the file embeds the containers into the file for easy use with FileMaker Go and offline functionality. <br />
<br />
PLEASE NOTE: there is an unexpected behavior in FIleMaker in this process: when saving the self-contained copy, FileMaker updates the modification timestamp for every record that has an external stored container field. That's not a problem normally, but when used with MirrorSync, it will make the initial sync very slow. The reason behind the slow initial is due to MirrorSync assuming that all of those records have been modified on the client, so it writes all of the server data to the client (including the container data). <br />
<br />
The workaround for this is to uncheck the modification timestamp auto-entry before saving the self-contained copy, and then turn it back on after the copy has been saved. This modification timestamp behavior has been reported to FileMaker, Inc. and will hopefully be resolved soon.<br />
<br />
====Q: Does MirrorSync do conflict resolution?====<br />
A:MirrorSync 1.2 introduced a choice of manual conflict resolution or automatic conflict resolution. If a user syncs their changes and a conflict arises, the user has an option of selecting either. Selecting manual conflict resolution will bring up an interface that highlights differences in the server and client copies. For each conflict, users can select which version of the record will win and MirrorSync will use that record. MirrorSync does not 'merge' changes - it will always pick one entire record as the winner of the conflict.<br />
<br />
Previous versions of MirrorSync, and automatic conflict resolution keep track of which change was made last, and selects that as the winner in a conflict. So if a record is changed at 2PM on one device, and 3PM on another device, the 3PM change will win the conflict. The exception is that changes always win over deletions, regardless of which one happened last. A common misconception is that conflict resolution is based on who syncs first or last - MirrorSync will pick the record that was EDITED last, not the one that was SYNCED last. Again, MirrorSync does not 'merge' changes - it will always pick one entire record as the winner of the conflict.<br />
<br />
====Q: Is MirrorSync transactional? What happens if the connection is lost while syncing?====<br />
A: MirrorSync is not 'transactional' in the strictest sense. If the connection is dropped during a sync, it is possible for records from one table to be written to the server, while records from another related table may not be written. However, MirrorSync keeps track of which records have been written and which ones have not, and it will resume from where it was on the next sync and complete everything as if the first sync had finished. If a record on the server cannot be written because it is being edited, the offline user will get a warning error message telling them this. MirrorSync will continue to retry that edit operation each time the sync script is run.<br />
<br />
====Q: Can I use external authentication with MirrorSync?====<br />
A: Yes, MirrorSync supports externally authenticated accounts with no modifications. So long as the username on the local copy matches the username on the server, you can set up one password for local access and another for external authentication with the server. The passwords do not need to match between the local file and the hosted file.<br />
<br />
====Q: How do I make changes to my hosted database if I have offline users who are syncing? Can I add fields and tables?====<br />
A: MirrorSync will match your fields by name whenever you sync. What this means is that as long as you don't rename or delete fields, you can freely add additional tables and fields to your hosted database without causing problems for your users working with the older databases running offline. Don't forget to add new fields to your sync layouts. To distribute your updated version of the database to users, re-run the configuration process and select any new fields and tables to add to the sync configuration. Be sure to re-copy your script steps for the MirrorSync script. Then download a copy of the database from the server and send it to your users to get them the newest version. Users running the old version will be able to sync until they are ready to download the newest version of the file.<br />
<br />
===Primary key / serial numbers===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: What is the difference between serial numbers and UUIDs? Which one should I pick?|What is the difference between serial numbers and UUIDs? Which one should I pick?]]<br><br />
[[#Q: I'm running FileMaker 12, and my primary keys are UUIDs. When I try to sync I get errors. What's going on?|I'm running FileMaker 12, and my primary keys are UUIDs. When I try to sync I get errors. What's going on?]]<br><br />
[[#Q: Do I need to change how my primary keys are generated?|Do I need to change how my primary keys are generated?]]<br><br />
[[#Q: After a couple of syncs I noticed that the serial numbers on my records don't match on my iPad and my laptop. Is this a problem?|After a couple of syncs I noticed that the serial numbers on my records don't match on my iPad and my laptop. Is this a problem?]]<br><br />
[[#Q: What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?|What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?]]<br><br />
[[#Q: Does the sync run any faster if you use UUIDs rather than serial numbers?|Does the sync run any faster if you use UUIDs rather than serial numbers?]]<br><br />
[[#Q: How do I configure and use two foreign keys as a primary key?|How do I configure and use two foreign keys as a primary key?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: What is the difference between serial numbers and UUIDs? Which one should I pick? ====<br />
When you pick 'serial numbers', MirrorSync does not write primary keys from one database to another - it lets each database generate its own primary keys, in a normal sequential order. This means that when record #4 on an iPad, for example, gets written to the server, it might get stored there with primary key #8, for example. MirrorSync records these two ID numbers and maintains its own internal map between the two. In the future, when changes are made to record #4 on the iPad, MirrorSync knows that it should make the changes to record #8 on the server, not #4. This means that you don't have to worry whether your primary keys for newly created records conflicts with the same primary key for different records on other devices. In addition, MirrorSync will re-write foreign keys, so that if any records related to record #4 on the iPad, MirrorSync will will store #8 in their foreign key field when it writes them to the server.<br />
<br />
When you pick 'UUID', MirrorSync will write the primary key unmodified to the other database. It is your responsibility to make sure that the same primary key is never created on multiple devices, otherwise there will be a conflict between two different records with the same primary key. There are many ways to accomplish this; MirrorSync does not know or care how you do it. Some examples are:<br />
* Using an auto-entered UUID for the primary key<br />
* Using simple serial numbers, but assigning different numeric ranges to different devices (ie. Tom creates records starting from 100,000, while Bob creates records starting from 200,000)<br />
* Prepending the user's initials or some other unique identifier to the primary key value<br />
* Using even numbers on one device and odd numbers on another (modify as necessary for more than two devices)<br />
* Getting the next serial number from some network source<br />
* Only allowing one database in the sync to create new records<br />
* Etc...<br />
<br />
In our testing, there is not a substantial benefit to one approach or the other. UUIDs are better if you ever need to merge databases without using MirrorSync. Serial numbers take less space and transmit across the network more quickly. We recommend using whichever approach you feel most comfortable with.<br />
<br />
====Q: I'm running FileMaker 12, and my primary keys are UUIDs. When I try to sync I get errors. What's going on?====<br />
A: Make sure that if you are using UUIDs as primary keys, the "Prohibit Modification of these Values" box is unchecked in the specify field window. MirrorSync must be able to write to these fields.<br />
<br />
====Q: Do I need to change how my primary keys are generated?====<br />
A: No. MirrorSync does not require primary keys to be unique across devices. If you pick the 'serial numbers' option, It will take care of keeping track of primary and foreign keys that are re-numbered when they are transferred to other devices.<br />
<br />
====Q: After a couple of syncs I noticed that the serial numbers on my records don't match on my iPad and my laptop. Is this a problem?====<br />
A: No, serial numbers are expected to be different between devices, because when a record is written from a mobile device to the server, another record may already exist with that same serial number. MirrorSync keeps track of which serial numbers are assigned to which records. For example, if the contact record 'Jesse Barnum' is ID #1 on your laptop, and the same record is #8 on the server, and the same record is #4 on your iPad, Then when a change to record #1 is written from your laptop to the server, MirrorSync knows to make the change to record #8. When you download the change on your iPad, MirrorSync knows to change record #4 on the iPad. It also updates all foreign keys that link to the primary key (this is why the foreign key mapping step is important in the setup process).<br />
<br />
====Q: What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?====<br />
As the previous FAQ points out, if you are using serial numbers for your primary keys, MirrorSync will renumber these serial numbers when it writes to another device to prevent number conflicts. However, this can be a problem for things like invoice numbers, that need to always be the same for all devices. This isn't really MirrorSync's "fault", because obviously if the devices are off-line from each other, there is no way to know what the next available serial number is if it might have been used by another off-line device.<br />
<br />
Before talking about solutions to this problem, it's important to emphasize that this user-friendly number should NOT be what you use as a primary key in your database. Primary keys are internal database identifiers, and should not do double-duty as a user-readable value, so even if you are not using MirrorSync, you should have two fields in your table: One hidden field used as a primary key that the user never sees, and then a second user-visible serial number that users can refer to. With that in mind, here are two potential solutions to the problem:<br />
<br />
1) Have a separate database file that is hosted on the server (not off-line) with a table that contains serial numbers. When you want to generate the next serial number, go to that online table, create a new record, and use that next serial number for your invoice number (or whatever user-visible field this is). Since this database is online, everybody shares it and nobody gets the same serial number. The downside of this is that you won't be able to create new records unless you have a network connection to the server, but the upside is that you can still get all of the speed benefits of working on your own offline copy of the database (since only the serial number table is hosted on the server).<br />
<br />
2) Either use a prefix for each device (so that records created on machine 'ABC' would be numbered ABC1, ABC2, ABC3, while records created on machine 'DEF' would be numbered DEF1, DEF2, DEF3), or assign a serial number range to each device (so records created on 'ABC' would be numbered 10,001, 10,002, 10,003, and records from DEF would be numbered 20,001, 20,002, 20,003). The downside to this approach is that your user-visible number will be longer, and also that you need to customize the database slightly for each device (either by changing the next serial number or by setting the prefix).<br />
<br />
If you'd like our assistance doing the integration and development for this, we'd be happy to help - please contact us for an estimate.<br />
<br />
====Q: Does the sync run any faster if you use UUIDs rather than serial numbers?====<br />
A: The choice of primary keys do not substantially affect the speed of processing data in MirrorSync. Serial numbers are somewhat more network efficient.<br />
<br />
==== Q: How do I configure and use two foreign keys as a primary key? ====<br />
A: In the configuration screen, use the drop down menus to select the two foreign keys. <br />
<br />
Please keep in mind primary keys need to be unique. If using two foreign keys, there may be an instance where an error occurs about a duplicate node ID, since FileMaker is not validating the fields together and making sure they are always unique in a table. To avoid this, make sure:<br />
<br />
#Ensure that the combination of two foreign keys only ever occurs once in the database.<br />
#If you need to be able to have multiple join table records with the same foreign keys, add a regular serial number field to the join table and use that as the primary key, instead of the compound foreign keys.<br />
<br />
===Performance questions===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: How fast is MirrorSync?|How fast is MirrorSync?]]<br><br />
[[#Q: How well does MirrorSync perform on slow networks?|How well does MirrorSync perform on slow networks?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: How fast is MirrorSync?====<br />
A: From a speed standpoint, there are three types of operations that MirrorSync does: 1) Initial sync, 2) syncing inserts and edits, and 3) syncing deletions. #1 and #3 are affected by the number of records in your database, but #2 is not.<br />
<br />
For each sync, there is an overhead associated with sync that is typically 1/4 - 1/2 of a second per table on a local network. Therefore, if you sync 20 tables, expect about 5 or 10 seconds in addition to the actual time to sync the records. For iOS devices, this is more like 2-3 seconds per table.<br />
<br />
For syncing inserts and edits, we find that 20 records per second going from server to client is a fairly typical benchmark. Therefore, if 100 records have been edited on the server, it should take about 5 seconds to sync these records to the client. This number will be higher or lower depending on how much information is stored in your records, and is more like 4 or 5 records per second for iOS devices.<br />
<br />
Syncing inserts and edits from the client to the server is about 5 records per second for FileMaker Server 11, and 40 records per second for FileMaker Server 12.<br />
<br />
Detecting deletions takes about 1 second per 1,000 records in your table. This can be time consuming if you have a large number of records. See the performance tips section below for tips on improving this.<br />
<br />
Initial sync takes about the twice as long as deletion - 2 seconds per 1,000 records in the table. This only happens the first time that a user syncs with an offline copy of the database.<br />
<br />
====Q: How well does MirrorSync perform on slow networks?====<br />
A: MirrorSync is very efficient over slow networks, because it sends very little data other than the actual record changes, and it transmits this information in large chunks, which is more efficient. There are 2 HTTP request at the beginning of the sync, and usually 2 HTTP requests per table that contains any modifications. For example, if you have a 20 table solution, and there are only changes in 5 of the tables, it will usually take 12 HTTP requests (2 + 2*5) to complete the sync. By comparison, the FileMaker home page takes 65 HTTP requests to load in a web browser.<br />
<br />
===Customizing MirrorSync===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?|I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?]]<br><br />
[[#Q: How does MirrorSync work with restricted accounts?|How does MirrorSync works with restricted accounts?]]<br><br />
[[#Q: I don't want users to have to click on the dialog that comes up at the end of the sync, can I hide that?|I don't want users to have to click on the dialog that comes up at the end of the sync, can I hide that?]]<br><br />
[[#Q: Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?|Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?]]<br><br />
[[#Q: Can MirrorSync run automatically every x seconds/minutes?|Can MirrorSync run automatically every x seconds/minutes?]]<br><br />
[[#Q: I have users in different time zones. Does MirrorSync account for that?|I have users in different time zones. Does MirrorSync account for that?]]<br><br />
[[#Q: My file is very large, and I want to give MirrorSync more memory allocation. How do I give Tomcat more memory?|My file is very large, and I want to give MirrorSync more memory allocation. How do I give Tomcat more memory?]]<br><br />
[[#Q: I want to sync very large containers and data. How can I increase the timeout limits?|I want to sync very large containers and data. How can I increase the timeout limits?]]<br><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?====<br />
A: That's a three-part question with a three-part answer. Just syncing certain tables is very easy: When you're configuring the sync using the MirrorSync configuration utility, only include layouts corresponding to the tables that you want to sync.<br />
<br />
Syncing certain fields is also very easy: Just don't include any fields on your sync layouts except the ones that you want to sync. You can also simply uncheck unwanted fields in the MirrorSync configuration utility.<br />
<br />
Syncing certain records is only slightly less easy: Utilize the record level access privileges in FileMaker's security management dialog to create custom restrictions. For example, you can easily restrict each user to only see their own records by creating a calculated restriction that checks to see if Get(AccountName) is equal to a field with an Account Name auto-entry option. With a little creativity, you can set up similar restrictions to only sync records with certain statuses, or which fall in certain date ranges.<br />
<br />
If you decide to use this technique to limit records based on access level privileges, you may choose to distribute an empty clone to your users instead of a full copy of the database. That way, the initial sync will only pull the records into their offline file that they have access privileges to on the database. Keep in mind that if they have access to many thousands of records, that could make the initial sync slower than if you distributed a full copy of the database that already contains all of the record data.<br />
<br />
====Q: How does MirrorSync work with restricted accounts?====<br />
<br />
MirrorSync requires a full access account only once: to paste in the table, scripts, and layout. After configuration, feel free to distribute copies of your file to restricted users. When MirrorSync does a sync, it logs in to the server copy as the user doing a sync, and won't be able to sync changes they don't have access to. See the above question for distributing empty clones, but please note the question above is more a guide on how to create these restricted accounts, and this question deals more with currently existing accounts. <br />
<br />
'''<big>WARNING</big>''': If you use a start up script that sets global variables which then determine access privileges, these privileges will not get set. The Web Publishing Engine in FileMaker does not run start up scripts, and so these globals won't be set when MirrorSync tries to write changes. A way to set up custom access instead would be to use the Get(AccountName), Get (AccountPrivilegeSetName) functions to determine access levels. This could avoid the start up script entirely.<br />
<br />
====Q: I don't want users to have to click on the dialog that comes up at the end of the sync, can I hide that?====<br />
A: Yes, set the global variable $$SILENT_MODE to "1" in your startup script. This will prevent MirrorSync from showing a dialog unless an error occurs.<br />
<br />
====Q: Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?====<br />
A: Yes, absolutely. Remember that the MirrorSync script is a regular FileMaker script that can be set to run at any time by the developer. For example, if there is a critical section of your application that you want to avoid conflicts, trigger the sync when the user navigates to that screen, and again when they are finished editing in that screen. You could make it so that checking a box, clicking a button, or any other condition that you choose can trigger the sync to happen. If you'd like to incorporate MirrorSync into your startup script, but you only want it to run the first time that user opens an offline file, you can switch to the MirrorSync table and do a search for any record that has a value in the 'lastClientToken' field. If there is at least one record matching the search, then this file has been synced before.<br />
<br />
====Q: Can MirrorSync run automatically every x seconds/minutes?====<br />
A: Yes, you can use an On Timer script to trigger this. However, keep in mind that when the script runs, it commits the current record and pops open a new window that could be open for a few seconds or longer. This could get annoying if it happens in the middle of something that the user is working on. For this reason, we recommend the approach in the previous FAQ entry of linking your script sync operations to some user-initiated action. The exception to this is unattended computers - if you want to have a computer that is running MirrorSync all the time for purposes of having an extra copy of the database replicated, without a user working on it, then by all means go ahead and use an On Timer script step (and be sure to see the FAQ above about disabling dialogs).<br />
<br />
====Q: I have users in different time zones. Does MirrorSync account for that?====<br />
A: Yes. When an offline client syncs with the server, one of the first pieces of information it sends to the client is the client's current time. The server compares this to its own clock to see how different the client is (whether from being in a different time zone or just the client's clock being wrong), and then it applies this offset amount to all the timestamps it receives from the client for writing modification timestamps and resolving conflicts.<br />
<br />
For online users connecting directly to the server, this offset cannot be calculated. Therefore, it is possible that online users in a different time zone, or whose clock is incorrect by more than 10 minutes (MirrorSync automatically includes a 10 minute "overlap"), could have their modifications missed by the sync process. To solve this problem, we recommend adding a new field, called something like 'Host modification timestamp', in addition to a regular modification timestamp field. Set the field type to 'Timestamp', and configure this auto-entered calculation:<br />
<br />
<pre><br />
Let( x=Modification timestamp; Get ( CurrentHostTimeStamp ) ) //Change modification timestamp to be whatever the name of your modification timestamp field is<br />
</pre><br />
<br />
<b>Be SURE to uncheck the box titled 'Do not replace existing value of field (if any)'.</b><br />
<br />
Repeat this step for every table. This Host modification timestamp should now be configured as the modification timestamp for MirrorSync.<br />
<br />
====Q: My file is very large, and I want to give MirrorSync more memory allocation. How do I give Tomcat more memory?====<br />
A: For some users, they may find that the default memory allocation is insufficient to transmit large amounts of data. To allocate more memory to Tomcat, modify the catalina.bat (for Win) or catalina.sh (for Mac) file in the Tomcat directory. To find that directory: <br />
<br />
:For FileMaker 11:<br />
:FileMaker Server/Web Publishing/publishing-engine/cwpe-tomcat/bin/<br />
:For FileMaker 12:<br />
:FileMaker Server/Web Publishing/publishing-engine/jwpc-tomcat/bin/<br />
<br />
Open the catalina.bat (for Win) or catalina.sh (for Mac), and find the following lines:<br />
<br />
<pre><br />
# FileMaker Server CWPE Tomcat Settings<br />
CATALINA_HOME="../../../../Common/Tomcat"<br />
CATALINA_BASE=".."<br />
JAVA_OPTS="-server -d32 -Xmx512M -DFMS.COMPONENT=cwpe -Dcom.prosc.devmode=true"<br />
</pre><br />
<br />
You can then change the -Xmx512M parameter to -Xmx1024M, which will double the memory available.<br />
<br />
====Q: I want to sync very large containers and data. How can I increase the timeout limits?====<br />
<br />
A: As of MirrorSync 1.4301, you can configure MirrorSync to override the default timeout values. To do so, you must find and modify the MirrorSync configuration XML file:<br />
<br />
Library/360Works/Applications/conf/Catalina/localhost/MirrorSync.xml '''OR''' <br><br />
Program Files/360Works/Applications/conf/Catalina/localhost/MirrorSync.xml <br />
<br />
Open this file with a text editor, and find the lines below. You can then modify these values to your own specifications. <br />
<pre><br />
<Parameter name="clientSecondsPerInsertion" value="1.5" /> <!--2 records every 3 seconds for non-container inserts--><br />
<Parameter name="clientSecondsPerContainerInsertion" value="15" /> <!--1 record every 15 seconds if we're inserting containers--><br />
<Parameter name="clientSecondsPerUpdate" value="5" /> <!--1 record every 5 seconds for normal updates--><br />
<Parameter name="clientSecondsPerContainerUpdate" value="15" /> <!--1 record every 15 seconds for updating containers--><br />
<Parameter name="clientSecondsPerDeletion" value="1" /> <!--1 record per second for deletions--><br />
<Parameter name="clientSecondsPerFetchRecord" value=".1" /> <!--10 records per seconds for getting changes records from client--><br />
<Parameter name="clientSecondsPerContainerFetchRecord" value="10" /> <!--1 record per 10 seconds for getting records from client that have one or more container fields--><br />
<Parameter name="clientSecondsPerFetchHeader" value=".03" /> <!--33 headers per seconds for just fetching primary key and modification timestamp (no record data)--><br />
</pre><br />
<br />
=== Licensing ===<br />
<br />
{| cellpadding="2" style="border: 1px solid darkgray;"<br />
|-<br />
| '''Contents''':<br />
[[#Q: Is MirrorSync included in the 360Works Portfolio Bundle?|Is MirrorSync included in the 360Works Portfolio Bundle?]]<br /><br />
[[#Q: From a licensing standpoint, what is a 'solution'?|From a licensing standpoint, what is a 'solution'?]]<br /><br />
[[#Q: Is there an unlimited device license for MirrorSync? What about for vertical market solutions?|Is there an unlimited device license for MirrorSync? What about for vertical market solutions?]]<br /><br />
[[#top|Back to top]]<br />
|}<br />
<br />
====Q: Is MirrorSync included in the 360Works Portfolio Bundle?====<br />
A: Yes, the Portfolio Bundle (http://360works.com/portfolio) includes MirrorSync. This is the same license as if it were purchased separately - up to 10 devices and 2 FileMaker solutions.<br />
<br />
====Q: From a licensing standpoint, what is a 'solution'?====<br />
A: From a business standpoint, a solution is one or more FileMaker database files that are integrated together for the purpose of meeting a particular business need. From a technical standpoint, there must be a single FileMaker file that contains external table occurrences in its relationship graph pointing to tables stored in other FileMaker data files. To be considered a single solution for purposes of MirrorSync licensing, a file must satisfy both the business and technical requirement.<br />
<br />
====Q: Is there an unlimited device license for MirrorSync? What about for vertical market solutions?====<br />
A: No, we do not offer an unlimited device license for MirrorSync. The same applies for vertical market solutions. For vertical market applications, we recommend that you pre-integrate your solution with MirrorSync, using the demo version of MirrorSync. Then tell your customers that if they would like to enable the offline sync feature, they can purchase MirrorSync separately, with no development work required. All that is needed is to install the MirrorSync software on their server, enter the license key using the admin utility, and customize the FileMaker sync script with the IP address of their MirrorSync server (this can be stored in a settings table, so that it doesn't have to be customized for each client / device).<br />
<br />
=== Miscellaneous questions ===<br />
<br />
====Q: Is MirrorSync localized into any non-English languages? Does it work in other languages?====<br />
A: At this time, MirrorSync is only localized to English. Our current focus is on adding features, but we anticipate translating this into other languages when the product is more mature. If you would like to offer help with translation, please contact plugins@360works.com to let us know. You should still be able to add MirrorSync to your solution in other languages, although we have discovered that copying and pasting the script steps does not work with other languages active - you must switch to English for this step of the configuration, and then you can switch back. Do so by editing your preferences in FileMaker Pro and selecting English in Windows, or by opening System Preferences in Mac, choosing English, and restarting FMP.<br />
<br />
====Q: I only have an offline copy of my file left, and need to upload it back to the server. What do I do?====<br />
A: Please note that this is an unsupported use of the offline file. But if necessary, users can reupload an offline copy of the file to FileMaker Server and use it with MirrorSync. Users will need to remove the "Client" record in the MirrorSync table, and keep only the "Server" record. Navigate to the MirrorSync layout, open the Debugging tab, and perform a find for "Server" in the type field. Select the inverse of the records found by pressing the pie icon in the status bar. Then, delete those other records.<br />
<br />
==Performance / speed optimization tips==<br />
'''Limit fields on the sync layout'''<br /><br />
It's a good idea to remove unnecessary fields on your sync layouts. Unstored calculations, summary fields, and related fields can cause significant slowdowns and are not synced anyway, so they should definitely be removed from the layout. Global fields and stored calculations do not affect speed as much, but they are not used for sync either so it's best to remove them if speed is important.<br />
<br />
'''Move container fields into their own separate table'''<br /><br />
When MirrorSync checks if a record has been modified, it looks at the modification timestamp. If a record has been changed, it downloads the entire record, including container fields, every time. By moving container fields off the regular sync layouts, MirrorSync will only download and upload containers when they have actually changed. To implement this optimization, create a new table that is used only to store the container fields. Put your containers fields in that table, and add a primary key and modification timestamp. Be sure to import all the actual container data from the old table to the new one. Then, take the containers off your current sync layouts (if you have already configured MirrorSync), and create a new layout for the container table. Be sure to re-run the MirrorSync configuration utility so that it knows about the new layout.<br />
<br />
'''Create layouts with just the ID and the modification timestamp'''<br /><br />
FileMaker 11 transmits data differently than FileMaker 12 to MirrorSync. This technique doesn't have any effect with FileMaker 12, but it may make the initial synchronization as well as deletion scanning much faster for FileMaker 11 tables with more than 1,000 records. For each Sync layout, create a new layout with the suffix _small. For example, you may have a table called Contacts. When you set up MirrorSync, you'd make SyncContacts. Now create another layout called SyncContacts_small. On this layout, place the primary key and modification timestamp ONLY. MirrorSync will automatically detect this layout and quickly scan for modification timestamps and records to add and delete. There is no need to rerun the configuration utility or script steps with this option. <br />
<br />
'''Flag records instead of deleting them'''<br /><br />
If you want to optimize performance here, it might make more sense to flag records as being deleted instead of actually deleting them. That makes it into an edit operation, which is not affected by the number of records in the table.<br />
<br />
== Troubleshooting/Known Issues ==<br />
<br />
=== The maximum number of users are currently using this copy of FileMaker Pro===<br />
<br />
[[File:MirrorSyncLicense.png|thumb|Example of error message]]<br />
<br />
There is a small bug in FileMaker Pro and FileMaker Pro Advanced that may occur when pasting the MirrorSync script, or editing the MirrorSync script. This occurs due to the references found in the script, which will reference both the internal and external IP address. FileMaker then opens both those references, which triggers the licensing server as two copies of FileMaker Pro. This error would occur for any script that contains both references to a single hosted file. <br />
<br />
There are three work arounds for this:<br />
<br />
# Upgrade your single user license to a volume license. You can contact FileMaker directly to upgrade your license if you have 5 or more copies.<br />
# Change your Data Sources to list the internal address first in both MirrorSync scripts. You should have either the data sources listing one IP each, or two data sources with two IP addresses. Either way, make sure that both have the internal address listed first, and then for the External source list the external IP in a second line. This will only call the internal IP references when opening the script, but will '''slow down syncs significantly.''' It will now try the internal IP address first, and if it unavailable, time out and then try the external address.<br />
# Paste the script and let FileMaker crash. The script will save appropriately. You will not need to modify the script after the initial configuration, so it should work correctly. If an update is released that requires changes to the script, be aware that any sync buttons or references to the MirrorSync script will have to be corrected on updates. <br />
<br />
If you require assistance on this issue, please let us know.<br />
<br />
=== The operation couldn’t be completed. (OSStatus error -67049.) === <br />
<br />
Apple's new Mountain Lion feature, Gatekeeper, prevents software from being installed outside the Mac App Store. However, you should be able to override Gatekeeper settings with right or control click. This way of getting around Gatekeeper does not always work correctly, and may result in the error message, "The operation couldn't be completed. (OSStatus error -67049)" To continue with MirrorSync or any other non App Store application, disable Gatekeeper completely in your System Preferences, perform the installation, and reenable once finished.<br />
<br />
As of MirrorSync 1.5, the installer has been completely rewritten and no longer encounters the issues with Gatekeeper's right or control click. <br />
<br />
=== Error from server: java.lang.IllegalArgumentException: Invalid date value (XXXXXXXXX) ===<br />
<br />
This error occurs when invalid timestamps are being used in timestamp fields. This could be due to legacy timestamps that were previously stored in text fields and then converted to timestamp fields. FileMaker will retain the preexisting data in the field, but will not allow new invalid data to be entered.<br />
<br />
The solution to this problem is to convert the existing invalid timestamps to equivalent timestamps in the correct format (MM/DD/YYYY HH:MM:SS). For example, if the contents of your timestamp fields appear like this YYYY-MM-DD HH:MM:SS you would isolate the found set of all records with invalid timestamps, and perform a Replace Field Contents operation with this code as the calculated result:<br />
::Let ( [<br />
<br />
::var.ts = Table::TimestampField ;<br />
::var.year = Left ( var.ts ; 4 ) ;<br />
::var.month = Middle ( var.ts ; 6 ; 2 ) ;<br />
::var.day = Middle ( var.ts ; 9 ; 2 ) ;<br />
::var.date = Date ( var.month ; var.day ; var.year ) ;<br />
::var.time = Trim ( Middle ( var.ts ; 11 ; 100 ) )<br />
<br />
::];<br />
<br />
::Timestamp ( var.date ; GetAsTime ( var.time ) )<br />
<br />
::)<br />
<br />
This code only works for invalid timestamps in one specific format (YYYY-MM-DD HH:MM:SS), but with only slight modification, it could be made to work with many different invalid timestamp formats.<br />
<br />
== More Help Sources ==<br />
<br />
If you still need help, there are several resources available! [http://fmforums.com/forum/forum/172-mirrorsync-by-360works/ FMForums] hosts a support forum for MirrorSync. Please look through the posts and see if your question has been posted before making a new topic.<br />
<br />
Support is also available via email at plugins@360works.com. You can also call us at 770-234-9293. <br />
<br />
We're confident you'll be able to configure MirrorSync quickly and easily. However, if you want to have us integrate MirrorSync your solution for you, it will take approximately an hour at our rate of $165. We'll take a look at your files first, and if the integration will take more than an hour we'll contact you. Contact us to learn more and get started!<br />
<br />
== Troubleshooting ==<br />
<pre><br />
http://server/fmi/xml/FMPXMLRESULT.xml?-dbnames<br />
http://server/fmi/xml/FMPXMLRESULT.xml?-db=<yourDb>&-lay=MirrorSync&-findany<br />
</pre></div>Sarahhttp://docs.360works.com/index.php/MirrorSync_3MirrorSync 32013-12-11T19:20:25Z<p>Sarah: </p>
<hr />
<div>{| cellpadding="10" style="margin: 1em auto 1em auto;" <br />
|- <br />
| colspan="2" | <center><big>Which docs do you need?</big></center><br />
|- <br />
| style="border: 1px solid darkgray;vertical-align:top;" | <span style="font-size:175%">[[MirrorSync basic setup]]</span> <p>Everybody who uses MirrorSync should read this section.</p><br />
| style="border: 1px solid darkgray;" | <span style="font-size:175%">[[MirrorSync advanced topics]]</span> <p>You should read this section if you:</p><br />
* Are a hosting provider<br />
* Want to customize the behavior of MirrorSync<br />
* Want to optimize the performance of MirrorSync as much as possible<br />
* Are getting an error message and want to check if it's a known issue<br />
* Are just curious!<br />
<br />
|}<br />
<br />
<br />
Or maybe you're looking for the old [[MirrorSync 1]] documentation?</div>Sarahhttp://docs.360works.com/index.php/MirrorSyncMirrorSync2013-12-11T19:20:05Z<p>Sarah: Redirected page to MirrorSync2</p>
<hr />
<div>#REDIRECT [[MirrorSync2]]</div>Sarahhttp://docs.360works.com/index.php/Main_PageMain Page2013-12-11T18:58:30Z<p>Sarah: </p>
<hr />
<div><center><big>'''Welcome to the 360Works Support Wiki!'''</big><br />
<br />
This page provides detailed instructions, how-to's, and configuration guides. Please select a product below, or view the general help at the end of the page.<br />
</center><br />
<br />
{| cellpadding="15" style="margin: 1em auto 1em auto;" <br />
|- align="center" <br />
| style="border: 1px solid darkgray;" width="175" | <big> [[Plugins 101|Plug-ins 101]]<br><br>[[Plugins 101|Start here if you're new to plug-ins!]]</big><br><br> Installing, using, and registering plug-ins<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[MirrorSync2|MirrorSync 2]]</big><br><br> [[File:Mirrorsyncico2.png|link=MirrorSync2]] <br> Sync FileMaker and SQL databases<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[DocuBin]]</big><br><br> [[File:Docubinico2.png|link=DocuBin]] <br> Document and digital asset management<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[SuperContainer]]</big><br><br>[[File:SCico2.png|link=SuperContainer]] <br> Upload, view, and download images and files<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[ScriptMaster]]</big><br><br>[[File:SMico2.png|link=ScriptMaster]] <br> Free, general-purpose, modular plugin<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[AdminAnywhere]]</big><br><br>[[File:Adminico2.png|link=AdminAnywhere]] <br> Administer FileMaker Server on the go<br />
|- align="center"<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[Zulu]]</big><br><br>[[File:Zuluicon2.png|link=Zulu]] <br> Sync calendars & contacts with iCal and Google<br />
| style="border: 1px solid darkgray;" width="175"| <big>[[EmailPlugin|Email]]</big> <br><br>[[File:Emailico2.png|link=EmailPlugin]] <br> Send and receive emails right in FileMaker<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[Plastic 2]]</big><br><br>[[File:Plasticico2.png|link=Plastic 2]] <br> Credit card processing plug-in for FileMaker Pro<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[WebServicesManager|Web Services Manager]]</big><br><br>[[File:WSMico2.png|link=WebServicesManager]] <br> Publish scripts as XML services<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[Scribe]]</big><br><br>[[File:Scribeico2.png|link=Scribe]] <br> The ultimate text processing plug-in<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[JDBC]]</big><br><br>[[File:JDBCico2.png|link=JDBC]] <br> Connect to any JDBC database to FileMaker<br />
|}<br />
<br />
<br />
<br />
<big>General Plug-in Support</big><br />
<br />
[[Send us a bug report]]<br><br />
[[Plugin autoupdate]]<br><br />
[[Plugin installation]]<br><br />
[[Plugin registration]]<br><br />
[[Plugin log files]]<br><br />
[[Autoupdate plugin location]]<br><br />
[[Security issues with Web Publishing]]<br><br />
[[Common issues]]<br><br />
[[Plugin failed to load]]<br><br />
[[Heapspace Out of Memory Error]]</div>Sarahhttp://docs.360works.com/index.php/MediaWiki:SidebarMediaWiki:Sidebar2013-12-11T18:57:58Z<p>Sarah: </p>
<hr />
<div>** http://www.360works.com|360Works Homepage**<br />
<br />
* Plug-in Products<br />
** plugins_101|Plug-ins 101<br />
**ScriptMaster|ScriptMaster<br />
**EmailPlugin|Email<br />
**Plastic 2|Plastic 2<br />
**Scribe|Scribe<br />
**JDBC|JDBC<br />
<br />
* Other Products<br />
**MirrorSync2|MirrorSync 2<br />
**DocuBin|DocuBin<br />
**SuperContainer|SuperContainer<br />
**AdminAnywhere|AdminAnywhere<br />
**WebServicesManager|Web Services Manager<br />
<br />
* navigation<br />
** mainpage|mainpage-description<br />
** recentchanges-url|recentchanges<br />
** randompage-url|randompage<br />
** helppage|help<br />
* SEARCH<br />
* TOOLBOX<br />
* LANGUAGES</div>Sarahhttp://docs.360works.com/index.php/MirrorSync_3MirrorSync 32013-12-11T18:57:14Z<p>Sarah: </p>
<hr />
<div>{| cellpadding="10" style="margin: 1em auto 1em auto;" <br />
|- <br />
| colspan="2" | <center><big>Which docs do you need?</big></center><br />
|- <br />
| style="border: 1px solid darkgray;vertical-align:top;" | <span style="font-size:175%">[[MirrorSync basic setup]]</span> <p>Everybody who uses MirrorSync should read this section.</p><br />
| style="border: 1px solid darkgray;" | <span style="font-size:175%">[[MirrorSync advanced topics]]</span> <p>You should read this section if you:</p><br />
* Are a hosting provider<br />
* Want to customize the behavior of MirrorSync<br />
* Want to optimize the performance of MirrorSync as much as possible<br />
* Are getting an error message and want to check if it's a known issue<br />
* Are just curious!<br />
<br />
|}<br />
<br />
<br />
Or maybe you're looking for the old [[MirrorSync]] 1 documentation?</div>Sarahhttp://docs.360works.com/index.php/Main_PageMain Page2013-12-11T18:56:39Z<p>Sarah: </p>
<hr />
<div><center><big>'''Welcome to the 360Works Support Wiki!'''</big><br />
<br />
This page provides detailed instructions, how-to's, and configuration guides. Please select a product below, or view the general help at the end of the page.<br />
</center><br />
<br />
{| cellpadding="15" style="margin: 1em auto 1em auto;" <br />
|- align="center" <br />
| style="border: 1px solid darkgray;" width="175" | <big> [[Plugins 101|Plug-ins 101]]<br><br>[[Plugins 101|Start here if you're new to plug-ins!]]</big><br><br> Installing, using, and registering plug-ins<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[MirrorSync2]]</big><br><br> [[File:Mirrorsyncico2.png|link=MirrorSync2]] <br> Sync FileMaker Pro and Go to Server<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[DocuBin]]</big><br><br> [[File:Docubinico2.png|link=DocuBin]] <br> Document and digital asset management<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[SuperContainer]]</big><br><br>[[File:SCico2.png|link=SuperContainer]] <br> Upload, view, and download images and files<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[ScriptMaster]]</big><br><br>[[File:SMico2.png|link=ScriptMaster]] <br> Free, general-purpose, modular plugin<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[AdminAnywhere]]</big><br><br>[[File:Adminico2.png|link=AdminAnywhere]] <br> Administer FileMaker Server on the go<br />
|- align="center"<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[Zulu]]</big><br><br>[[File:Zuluicon2.png|link=Zulu]] <br> Sync calendars & contacts with iCal and Google<br />
| style="border: 1px solid darkgray;" width="175"| <big>[[EmailPlugin|Email]]</big> <br><br>[[File:Emailico2.png|link=EmailPlugin]] <br> Send and receive emails right in FileMaker<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[Plastic 2]]</big><br><br>[[File:Plasticico2.png|link=Plastic 2]] <br> Credit card processing plug-in for FileMaker Pro<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[WebServicesManager|Web Services Manager]]</big><br><br>[[File:WSMico2.png|link=WebServicesManager]] <br> Publish scripts as XML services<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[Scribe]]</big><br><br>[[File:Scribeico2.png|link=Scribe]] <br> The ultimate text processing plug-in<br />
| style="border: 1px solid darkgray;" width="175" | <big>[[JDBC]]</big><br><br>[[File:JDBCico2.png|link=JDBC]] <br> Connect to any JDBC database to FileMaker<br />
|}<br />
<br />
<br />
<br />
<big>General Plug-in Support</big><br />
<br />
[[Send us a bug report]]<br><br />
[[Plugin autoupdate]]<br><br />
[[Plugin installation]]<br><br />
[[Plugin registration]]<br><br />
[[Plugin log files]]<br><br />
[[Autoupdate plugin location]]<br><br />
[[Security issues with Web Publishing]]<br><br />
[[Common issues]]<br><br />
[[Plugin failed to load]]<br><br />
[[Heapspace Out of Memory Error]]</div>Sarahhttp://docs.360works.com/index.php/MirrorSync_advanced_topicsMirrorSync advanced topics2013-12-11T18:55:47Z<p>Sarah: Created page with "Welcome to the advanced section of the MirrorSync documentation! This guide will help you customize MirrorSync to suit your development needs, and provide detailed instruction..."</p>
<hr />
<div>Welcome to the advanced section of the MirrorSync documentation! This guide will help you customize MirrorSync to suit your development needs, and provide detailed instructions for various situations. If you would like a good general overview of the software, please read through [[MirrorSync basic setup]] first!<br />
=== Deployment questions===<br />
<br />
====How do I uninstall MirrorSync?====<br />
To uninstall on Mac, run the 'Mac Uninstaller.pkg' that comes with the MirrorSync. On Windows, run 'C:\Program Files\360Works\Uninstall.<br />
<br />
====Installation for hosting providers====<br />
To install multiple instances of MirrorSync, choose the Hosting provider option in the installer. This is exactly the same as the regular installation process, except that it will allow you to rename the instance of MirrorSync. You can continue running the installer as many times as you like, once per client, renaming each instance to something unique. These copies can then be managed via the 360Admin utility, which is found either in your Program Files or Applications folder. When installing additional instances of the application, only a single Tomcat process will be installed which is shared by all of the MirrorSync instances.<br />
<br />
We recommend you use the installer. We at 360Works use the installer for our hosting clients as well, and find it easy to update and manage. If you are curious as to what the installer actually does, it modifies and adds the following:<br />
<br />
* Creates a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows that is readable and writeable.<br />
* Downloads and installs an instance of [http://tomcat.apache.org/download-60.cgi Tomcat 6] into that folder. (Only one copy of Tomcat is installed, regardless of how many copies of MirrorSync are running)<br />
* Copies and renames the installer's MirrorSync.war, which deploys the web app, as well as the other supporting material into the folder.<br />
* Adds a launch daemon in Library/LaunchDaemons in OS X, or creates a Windows Service to automatically start Tomcat.<br />
* Modifies the http.conf file for Apache to allow for URL redirection. If using Windows with IIS, we create an ISAPI filter or a URL Rewrite rule for the URL redirect.<br />
* Copies a lightweight Admin Utility JAR file to manage Tomcat to either C:\Program Files\360Works or /Applications.<br />
<br />
If upgrading from an older version of MirrorSync, we'll copy over the SyncData and remove the URL redirects for the old MirrorSync.<br />
<br />
If you prefer MirrorSync to be deployed to your own instance of Tomcat that you've set up, please note and follow these instructions:<br />
<br />
# Create a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows. Make sure that it is readable and writeable to the process that Tomcat is running as. This is where MirrorSync stores its private data including the internal sync database and the stored configurations. If you have a strong preference for locating this someplace else, because of disk space for example, set the '360directory' system property to point to some other path.<br />
# Rename the MirrorSync.war file to whatever name you'd like the instance to run as for your hosting customer, ie. 'CustomerXSync.war' If you decide to run multiple instances of MirrorSync with the same name (using multiple instances of Tomcat), you'll need to set '360directory' separately for each Tomcat instance, otherwise those multiple instances will overwrite each other's private data.<br />
# Drop that .war file into the webapps directory in your Tomcat instance.<br />
# Modify the the MirrorSync.xml context descriptor and set the administrative username and password for MirrorSync. In Tomcat 6, this file is automatically written to the Tomcat/conf/Catalina/localhost. If you are running Tomcat 7, the file is located in the webapps/MirrorSync/META-INF/context.xml file, or you can follow the instructions at http://tomcat.apache.org/tomcat-7.0-doc/config/host.html regarding copyXML to get the same behavior as Tomcat 6 (we recommend doing this, so that you don't lose the context.xml file every time the application is redeployed).<br />
# If necessary for your configuration, set up URL forwarding from IIS / Apache to your Tomcat connectors. [http://tomcat.apache.org/tomcat-6.0-doc/index.html See tomcat documentation on how to do this].<br />
<br />
==== Split server deployments ====<br />
If your FileMaker deployment is split onto multiple machines, we recommend installing MirrorSync on the FileMaker Server machine. This allows the download database feature in MirrorSync to work, which greatly simplifies deployment to end users. If you will not use the download database feature, and you do not plan on sending download URLs to your users, then install MirrorSync on the web server, for maximum speed during syncing.<br />
<br />
Regardless of which computer you install on, be sure that when you are configuring MirrorSync, you specify that the MirrorSync / FM Server machines are on different computers. This option is on the first screen in the new configuration process.<br />
<br />
====Does MirrorSync work with runtime versions of FileMaker Pro?====<br />
MirrorSync is untested and unsupported for use in this configuration. In addition, the legal licensing agreement for creating runtime versions of FileMaker specifically disallows any automated transfer of data between the runtime version and FileMaker Server. This restriction means that no sync process can legally be used to transfer data between the runtime edition and FileMaker Server, whether that is from a 3rd party or a home-grown automation process. Contact your FileMaker Business Account Manager for volume pricing on FileMaker Pro licenses.<br />
<br />
====What if I need to redeploy FileMaker Server?====<br />
If using a Mac, no additional steps should be required. However, if you are running Windows, you'll want to rerun the installer for MirrorSync.<br />
<br />
<div id="upgradeFrom1"></div><br />
====I am running MirrorSync 1. What do I need to do to upgrade to 2?====<br />
Any extra configurations or devices you purchased with MirrorSync 1 will carry over to MirrorSync 2 after purchasing the upgrade.<br />
<br />
# First, have all of your offline users run a sync. They will need to replace their offline files with new versions, so this will prevent them from losing any data.<br />
# MirrorSync 2 requires a creation timestamp field, in addition to the modification timestamp. Create that field if you do not already have one, and be sure to add it to all the MirrorSync layouts.<br />
# Run the MirrorSync installer. MirrorSync 1 configurations will not be preserved, so you'll need to create new configurations and distribute new copies of the files to your users. The good news is that since you already have all of your sync layouts ready to go, and also since MirrorSync 2 automatically detects foreign keys (requires FileMaker Server 12 or later), this shouldn't take much time at all.<br />
# Download new copies of the file for your users, and enjoy all the great features and speed of MirrorSync 2!<br />
<br />
=== Networking questions ===<br />
<br />
====Can MirrorSync send encrypted data? What about SSL enabled FMS?====<br />
<br />
Yes, it can. To make sure data is encrypted, you'll need a valid SSL certificate installed on the web server where MirrorSync is running. This will ensure that all plain-text data is sent and received encrypted with SSL. To sync container data using SSL, first set up FileMaker server as SSL enabled ([http://www.filemaker.com/downloads/documentation/fm12_security_guide_en.pdf see page 20 of these docs]). After doing so or if FileMaker Server is already is SSL enabled, check the SSL checkbox when configuring MirrorSync. <br />
<br />
If you get an error saying that you have a self-signed certificate, then you will need to follow the [[Custom SSL Certificate setup instructions]].<br />
<br />
<br />
====I need my database to be HIPPA compliant, what should I do with MirrorSync?====<br />
HIPPA compliance depends on a large number of requirements. However, one of those requirements is to transmit only encrypted data. See the question above if you experience difficulties. Please keep in mind that encryption is one piece of HIPPA compliance, so consult the [http://www.hhs.gov/ocr/privacy/ Department of Health and Human Services] for more information.<br />
<br />
<br />
====What ports are required for MirrorSync? Can I change them?====<br />
MirrorSync transmits container data on port 5003, which is the regular port for communication betwen FileMaker Pro and FileMaker Server. All other field types (text, number, date, time, timestamp) are transmitted using regular HTTP communication, which typically runs on port 80, or port 443 if SSL encryption is being used. These port numbers are set in your web server configuration (IIS on Windows or Apache on OS X), and can be customized to any value you prefer. A good way to test this is to test the FileMaker Web Publishing Engine - if the URL 'http://yourServer:somePort/fmi/xml/FMPXMLRESULT.xml?-dbnames' returns an XML list of database names, then it should work for MirrorSync as well.<br />
<br />
====Will MirrorSync work on a VPN?====<br />
Yes. MirrorSync runs over standard HTTP protocols (which are VPN compatible) for non-container data, and standard FileMaker protocols (which are also VPN compatible) for container data.<br />
<br />
====My solution is behind a firewall. Will MirrorSync still work?====<br />
MirrorSync communicates with FileMaker Server using a web viewer, so as long as the firewall allows standard HTTP traffic on port 80 (almost all firewalls are configured to allow this), all of your sync devices should be able to access it through the firewall. The exception to this is container fields. If you are syncing container fields, you will need to make sure that port 5003 (FileMaker's standard port) is open on the firewall, because the client needs to connect as a guest of the server to transfer container data.<br />
<br />
<div id="nat"></div><br />
<br />
==== Is MirrorSync compatible with Network Address Translation (NAT)? ====<br />
Yes. When configuring MirrorSync, select the option that says 'My internal and external IP addresses are different.' This will write the sync script so that if it detects it's running on the same LAN as MirrorSync, it will use the internal IP address, and if it's running outside the MirrorSync LAN, it will automatically switch to the external IP address.<br />
<br />
<br />
<br />
<br />
===Primary key / serial numbers===<br />
<br />
====What is the difference between 'MirrorSync-managed' and 'Developer-managed' primary keys? Do I need to change how I do my primary keys? Which one should I pick? ====<br />
Before answering this question, it's first necessary to explain why primary keys are a complex issue with synchronization. With traditional incrementing serial numbers, one database might have records numbered 1 through 10. Another database might have records 1 through 50. If we create a new record on the first database, it will get assigned the next number in the sequence (11). However, if we try to write that record to the second database, it will conflict with record 11 that already exists there. Here are several approaches to solving that problem:<br />
# '''Use Universally Unique Identifiers (UUIDs) as primary keys'''. These are typically long, 36-character strings that look like this: "D2EF9F69-5DEA-4FE3-9095-162C77F76FBF". They are sufficiently random to statistically eliminate the possibility of duplicate values. This makes them ideally for syncing databases - you can safely write records from one database to another without worrying about conflicting IDs. MirrorSync (and most other sync frameworks) supports UUIDs.<br />
# '''Combine a traditional serial number with some delimiter''', such as each user's initials or a file ID. This way, user 1 would have primary keys "1.1", "1.2", "1.3", and so on. User 2 would create primary keys "2.1", "2.2", "2.3", etc. This has the advantage of being shorter and more readable than UUIDs, but the added management consideration of assigning unique identifiers to each user. MirrorSync can manage this for you, as explained later.<br />
# A variation on the second solution would be to '''assign each user a particular numeric range''', so that user 1 generates primary keys in the range of 1-10,000; user 2 generates primary keys 10,001-20,000; and so on. This has the advantage of pure numeric values (instead of text), but the disadvantage of the possibility of conflicts if a user exceeds the expected number of records. MirrorSync can manage this approach as well.<br />
# A very different approach is to '''allow conflicting primary keys to exist on each separate database, without ever writing those primary keys to other databases'''. When record #11 is written from the first database to the second (in our original example), instead of being written with primary key 11, it is written with primary 51 (the next number in the sequence on the second database). This has the advantage of the shortest possible primary keys, which are pure numeric values, with no possibility of conflicts. It is also the way that the majority of existing databases are designed. MirrorSync supports this method (and is the only sync framework that does, to our knowledge). It creates an internal table to translate between the primary keys on all database that are syncing, so that when record #11 is later updated, MirrorSync knows to change record #51 in the second database. MirrorSync also re-writes foreign keys when they are written from one database to another, so that foreign keys that contained '11' on the first database will be re-written with '51' in the second database.<br />
<br />
Options 1, 2, and 3 are considered ''''Developer-managed'''', because MirrorSync writes the primary keys unmodified between the databases being synced. It is the developer's responsibility to pick some scheme that ensures that the same primary key is never used for different records on different databases. There are other variations on the same theme (ie. one database gets odd numbers and the other gets even numbers), but they all are treated the same by MirrorSync.<br />
<br />
Option 4 is considered ''''MirrorSync-managed'''.' The developer is not responsible for the uniqueness of primary keys across different databases; MirrorSync takes care of this for you.<br />
<br />
As to which you should pick, the answer is usually this: If your FileMaker database is currently using UUIDs, use developer-managed. If your database is written using traditional serial numbers, you should use MirrorSync-managed. However, if you need 'user-friendly' numbers for things like invoice numbers, job numbers, or check numbers, [[#writebacks|read the next FAQ]] on user-friendly serial numbers before making a decision.<br />
<br />
If you are building a new database and can use whichever approach you want, here are the relative advantages:<br />
* Serial numbers are more efficient because they are smaller. [[#What can I do to speed up syncing?|<br />
See the performance section of this documentation]] for more discussion on this.<br />
* UUIDs are easier to use if you need to ever sync or import manually, or switch to some other sync framework.<br />
<br />
<div id="writebacks"></div><br />
<br />
====What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?====<br />
The problem with MirrorSync-managed serial numbers is that they are not suitable for user-visible numbers, such as invoice numbers. That's because the primary key will be different on one device than another. If you're using the primary key serial number as your invoice number, it is clearly a problem if your invoice number is different between your laptop and the server!<br />
<br />
There are several solutions to this problem. One of the first things to establish is whether your database uses a single field as both the primary key and the user-visible value (we'll refer to it as the 'invoice number'). It is always preferable (even when not syncing) to have these be separate fields from each other. Invoice numbers / job numbers / user visible numbers should NOT be what you use as a primary key in your database. Primary keys are internal database identifiers, and should not do double-duty as a user-readable value.<br />
<br />
If the fields are separate, the problem becomes simpler to solve, because you have the flexibility to change the value of the invoice number without breaking relationships. See the section below on write-back values for the recommended approach.<br />
<br />
If the same field is being used for the primary key and the invoice number, and if it is feasible to split this into two separate fields (one for relationships, and one for display/searching), you should do so. Unfortunately, this can sometimes be a very big job - creating the new field is easy, but then you either need to find every place that that field is used in the user interface and point it to the newly created invoice number field, or else you need to find every place that it is used in the relationship graph and re-point that to the newly created primary key field. If you do not want to do this, then see the section below on MIRRORSYNC_CLIENTID for the recommended approach.<br />
<br />
{{mbox <br />
| type = warning<br />
| text = <b>One mistake you should be careful to avoid is this:</b> If your database is currently designed with serial numbers for primary keys, do not try to short-cut the solution by simply creating a new UUID field and try to trick MirrorSync into using that as your primary key. MirrorSync won't re-number your foreign keys, which means that the wrong children records will point to the wrong parent records when the records are synced with the server.}}<br />
<br />
===== Write-back values for user-visible numbers =====<br />
Let's say that you have a UUID as your primary key field, as well as an invoice number field. Using the write-back approach, the invoice number field will be blank when a record is created in an offline file. When that invoice record is synced to the server, it will get assigned the next invoice number, and that number will be written back to the invoice number field on the offline file. This approach does not work unless the invoice number field is separate from the primary key.<br />
<br />
Advantages of this approach:<br />
* Invoice numbers are in a simple, short numeric sequence, just like they would be without syncing.<br />
<br />
Disadvantages:<br />
* The offline file does not get an invoice number until the record is synced for the first time.<br />
<br />
To use this approach, follow these steps:<br />
* If you do not already have a serial number field in your table, create one. If you have a serial number which is used as a primary key, that's usable. We'll call that field 'serialNumber' in our example.<br />
* Define your invoiceNumber field this way: <code>If( Get( MultiUserState ) = 2; serialNumber; "" )</code>. This will leave the invoice number blank when working offline, but fill it in when connected directly to the server.<br />
* In the primary key selection screen in MirrorSync, select invoiceNumber as the write-back field. This will cause MirrorSync to write invoiceNumber from the server back to the offline file when the record is first synced.<br />
* Your choice of MirrorSync-managed or Developer-managed is unaffected by this setting; pick appropriately depending on whether you are using serial numbers or UUIDs as your primary key.<br />
<br />
===== MIRRORSYNC_CLIENTID for user-visible numbers =====<br />
Let's say that you have a single serial number as your primary key, which is doing double-duty as an invoice number field. You can use the $$MIRRORSYNC_CLIENTID global variable to help. Using this approach, MirrorSync ensures that each file being synced gets assigned a unique sequential number, starting from 1. You can use this number in conjunction with a traditional serial number to create a unique number than can be used as a user-visible field as well as a primary key. The serial numbers will either be text (ie. "1.1", "1.2", "1.3"…) or numeric (10,001 for user 1, 20,001 for user 2, 30,001 for user 3…).<br />
<br />
Advantages of this approach:<br />
* Reasonably short user-visible numbers<br />
* IDs are assigned immediately upon record creation, without needing to wait for syncing<br />
<br />
Disadvantages:<br />
* Offline users must do an initial sync before they can create records.<br />
* Requires a startup script to run, which means it won't work with custom web publishing applications.<br />
* IDs are not sequential, so you can't assume that an ID with a higher value was created before or after another ID.<br />
* If you are using numeric version, limits users to creating a fixed number of records before they start conflicting.<br />
* If you are using text version, you must switch all primary key and foreign fields from 'number' type to 'text.'<br />
* Setup is a bit more complex than write-back fields.<br />
<br />
To use this approach, follow these steps:<br />
* Set the 'MirrorSync setup' script as your startup script. If you already have a startup script, call the 'MirrorSync setup' script from your existing script. This will set the $$MIRRORSYNC_CLIENTID global variable. This clientId field is stored in the MirrorSync table, and is assigned when the user does their first sync. Each synced database will get a unique, sequential clientId. Manually run the script now to set that global variable before proceeding.<br />
* We assume you have a serial field called 'serialField'. Start off by duplicating this field, to create a new field called 'serialField copy.'<br />
* Change serialField to an auto-enter calc. Uncheck the box that says 'Do not replace existing value'. Also make sure that the 'Prohibit modification of value during data entry' is unchecked. Set the formula to one of the following:<br />
For text keys, use this formula (feel free to modify as desired):<br />
<pre><br />
$$MIRRORSYNC_CLIENTID & "." & serialField copy<br />
</pre><br />
for numeric keys, use this formula (replace whatever number you want instead of 10,000 to give wider or narrower range of numbers):<br />
<pre><br />
$$MIRRORSYNC_CLIENTID * 10000 + serialField copy<br />
</pre><br />
If you use the text version, be sure to change the field type from number to text. Also change all foreign keys that relate to it to text.<br />
* For primary key configuration in MirrorSync, select Developer-managed.<br />
<br />
<br />
<div id="compoundkey"></div><br />
==== How do I configure and use two foreign keys as a primary key? ====<br />
This is a common configuration for join tables in many-to-many relationships. In the primary key configuration screen, use the drop down menus to select the two foreign keys.<br />
<br />
Please keep in mind primary keys need to be unique. If using two foreign keys, there may be an instance where an error occurs about a duplicate node ID, since FileMaker is not validating the fields together and making sure they are always unique in a table. To avoid this, make sure:<br />
<br />
#Ensure that the combination of two foreign keys only ever occurs once in the database.<br />
#If you need to be able to have multiple join table records with the same foreign keys, add a regular serial number field to the join table and use that as the primary key, instead of the compound foreign keys.<br />
# The foreign key fields must both have the 'Not empty' validation in order to appear in the pull-down menu of eligible fields. If your join table needs to have foreign keys that may be empty, you should add a traditional single primary key to the table instead of using compound foreign keys as an identifier for MirrorSync.<br />
<br />
===Configuration questions===<br />
<div id="differentfile"></div><br />
==== Does MirrorSync need the databases being synced to be identical? ====<br />
No, not in MirrorSync 2. MirrorSync is able to sync between databases with completely different tables and fields from each other. In addition, it can sync just a subset of records, fields, and tables. If you are syncing different databases, for example a dedicated mobile file with a much larger server database, select the option 'Sync with a separate mobile file' (for FileMaker Go) or 'Sync with a separate server file' (for server-to-server sync). With this option selected, MirrorSync will allow you to match up your layout and field names with a simple drag and drop interface.<br />
<br />
====I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?====<br />
After converting your file, you'll need to edit the configuration and replace the MirrorSync script steps with ones generated for the FileMaker 12 file. This is due to the fact that the "Insert from URL" script step doesn't exist in FileMaker Pro 11.<br />
<br />
====Why does MirrorSync need to know about foreign keys?====<br />
MirrorSync uses foreign keys for two purposes. If you are using MirrorSync-managed primary keys, then it needs to know about the foreign keys because it needs to rewrite them when it writes between databases (see the primary key section above).<br />
<br />
In addition, even if you're using developer-managed primary keys, MirrorSync needs to know about relationships so that it can sync parent tables before children tables. This allows validation rules that check referential integrity to work correctly.<br />
<br />
MirrorSync 2 adds a new feature that automatically detects foreign keys, if you are using FileMaker 12 or later, so this step should not add any time to the configuration process. If you are using FileMaker 11 AND you are using developer-managed primary keys AND if you do not have any referential integrity validation making sure that foreign keys point to valid parent records, you can safely skip this step.<br />
<br />
====I'm not seeing my databases from the Choose database button. What's happening?====<br />
Make sure XML publishing is enabled for the account you are using in MirrorSync. Also be sure the database is accessible from the machine you are installing MirrorSync on.<br />
<br />
To test the XML Web Publishing Engine, try going to the URL <code>http://yourServer/fmi/xml/FMPXMLRESULT.xml?-dbnames</code>. You should see an XML document listing the databases in FileMaker Server. If you do not, or find a 404 or 401 error, then the XML Web Publishing Engine may not be configured correctly. Contact FileMaker tech support for help getting this running.<br />
<br />
If there is an authentication required at that test URL, try disabling IIS authentication. FileMaker Server authenticates its password-protected databases; however, this method disables the IIS authentication layer. This will also disable authentication for other websites that are using IIS on that server.<br />
<br />
# From the Control panel, navigate to Administrative Tools > Internet Information Services (IIS) Manager<br />
# Select the website in IIS and choose Action > Properties<br />
# Navigate to the Directory Security pane, and select Edit for authentications. This button may differ in various Windows versions.<br />
# In the Authentications Methods pop up:<br />
#* Make sure Anonymous Access is enabled<br />
#* For Authenticated access, disable the authentication methods.<br />
# Press OK<br />
<br />
<br />
==== Configuration without FileMaker Pro Advanced ====<br />
<br />
Since FileMaker Pro does not have the ability to copy and paste tables, you'll need to follow these instructions to create the MirrorSync table.<br />
<br />
*Locate the XML schema that came with your MirrorSync download.<br />
*Open FileMaker Pro and navigate to File -> Import Records -> XML Data Source.<br />
*In the "Specify XML and XSL Options" window, choose the "File" radio button, then click "Specify...".<br />
*Navigate to your MirrorSync download folder and choose the MirrorSync.xml file from the XML Schema subfolder.<br />
*Click continue to bring up the Import Field Mapping window. <br />
*Open the "Target" drop down menu, and select "New Table ("MirrorSync")"<br />
*Verify that the source fields and target fields have been matched correctly.<br />
*Click import.<br />
<br />
After the table is created, you'll need to modify some of the fields:<br />
*Navigate to File -> Manage -> Database...<br />
*Navigate to the "Fields" tab, highlight the "id" field and click the "Options..." button.<br />
*Check the box next to "Serial Number." Set it to generate on creation.<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the boxes next to "Not Empty" and "Unique Value" then press OK.<br />
*Next, highlight the "modstamp" field and click the "Options..." button.<br />
*Check the box next to "Modification" and ensure that the drop down menu says "Timestamp (Date and Time)."<br />
*Check the box next to "Prohibit modification of value during data entry."<br />
*Navigate to the "Validation" tab and check the box next to "Not Empty" then press OK<br />
*Finally, highlight the "container" field, and select "Container" from the "Type" drop down menu, next to the "Options..." button.<br />
<br />
You are now finished manually configuring your MirrorSync table. Click the OK button to close the database management window, and return to the MirrorSync configuration. (Be sure to save your changes!)<br />
<br />
====How do I configure External SQL Source (ESS) tables?====<br />
MirrorSync supports ESS tables, but it's very slow compared to using MirrorSync to simply sync the database from the external SQL database into your FileMaker Server. We do not recommend ESS unless syncing is not an option for some reason.<br />
<br />
If you would like to use ESS tables, there are additional steps. First, configure MirrorSync in its entirety. You should be able to select your ESS tables and files in the configuration utility. After you have pasted the last script step, download a copy of the file as usual. <br />
<br />
At this point, you need to make some modifications for the file to work offline. Open the downloaded copy, and make the following modifications to the local copy ONLY! Do not run the sync yet.<br />
<br />
* First, delete the data source. This is vital to preventing duplicate records and other artifacts of using ESS. Open File > Manage > External Data Sources and delete the OBDC data source.<br />
* Next, open the File > Manage > Database and navigate to the Tables tab. Copy any ESS tables. Then delete them. Make sure NOT to delete the table occurrences. After all the italicized tables are gone, paste the tables back in. This ensures they are local FileMaker files, not references to external data.<br />
* Make sure the primary keys, modification timestamps, and creation timestamps are correct. The primary key needs to be an auto-entered serial number or generated UUID.<br />
* Open the relationships tab in the File > Manage > Database and relink the missing tables.<br />
<br />
You can now distribute this file for synchronization to your users. Make a copy of this file and send it to each user who needs a copy. These copies are then ready for synchronization.<br />
<br />
===Sync questions===<br />
<br />
==== Does MirrorSync work with timezones? ====<br />
Yes and No.<br />
<br />
For offline users who are syncing, Yes. When MirrorSync gets a list of all modifications, it will automatically detect the offline user's timezone and clock drift and compensate for it.<br />
<br />
For server-to-server sync, Yes. MirrorSync can detect FileMaker server's current time and compensate for it, just like it does for offline users.<br />
<br />
For non-syncing users connecting directly to FileMaker Server, No, not automatically. You'll need to perform a small work around to make this work. It gets a little complicated, so an example makes it more clear. Let's say your FileMaker Server is hosted in New York. A user in New York runs a sync at 12:30 PM Eastern Time. 30 minutes later, a user in San Francisco modifies a record on the server at 10 AM Pacific Time (1 PM Eastern Time). Due to the way that FileMaker Server works, that modification timestamp on the server in New York will say 10 AM. It will not be converted to Eastern Time, nor will FileMaker Server store any time zone information for anybody to tell that it was actually representing Pacific time. Essentially, it's just an incorrect value. When the next sync runs, MirrorSync is going to request records modified since the last sync at 12:30 PM, which is going to miss the change made by the San Francisco user, even though it was made since the last sync.<br />
<br />
The solution to this problem is very easy - it actually takes less time to do than it did to read that explanation! Let's say that your table contains a regular modification timestamp called 'Modification timestamp'. Create a new field called 'Host modification timestamp' (or whatever you prefer), and set it to auto-enter this calculated value:<br />
<pre><br />
Let( x=Modification timestamp; Get ( CurrentHostTimeStamp ) ) //Change modification timestamp to be whatever the name of your modification timestamp field is<br />
</pre><br />
<b>Be SURE to uncheck the box titled 'Do not replace existing value of field (if any)'.</b><br />
<br />
Use this field as the modification timestamp in the MirrorSync configuration process, instead of the regular modification timestamp.<br />
<br />
This works by using the FileMaker Server clock, instead of the user's clock, for the modification timestamp. Now, when the San Francisco user modifies a record at 10 AM Pacific Time, FileMaker Server will store 1 PM (the server's local time when that change was made) in the Host modification timestamp field, and MirrorSync will work with time zones correctly.<br />
<br />
====Why can't I transfer my database to another computer after I've synced it?====<br />
The MirrorSync server stores information about each device that syncs with it. This includes the primary key, as well as the count of modifications for that record on that particular device. If this file were to be synced from two different devices, this information would conflict and cause problems. If you do try to send a database to another device and sync it, an error message will appear and the sync will be prevented.<br />
<br />
====Can I share a device among multiple users?====<br />
Yes, but…<br />
<br />
If all users on that device log in with the same username, then it's <i>probably</i> OK, as long as you make sure that you are not using record level access privileges on the offline device that would grant different record access to different users.<br />
<br />
If you want each user who shares a device to log in with different usernames, then the solution is to put a separate copy of the file on the device, one for each user. Make sure that each user is only able to login to the file that is assigned to them.<br />
<br />
MirrorSync prevents multiple users with different usernames from sharing the same offline file, because if record level access privileges or script filters were configured differently for each user, that would lead to the sync process incorrectly deleting the wrong records on the server, which would be very bad.<br />
<br />
====Does MirrorSync sync container fields?====<br />
A:Yes, MirrorSync works with FileMaker container fields. Container fields do take longer than other field types to synchronize, so remove them from your sync layouts if you don't need them to be synced.<br />
<br />
<br />
====What about SuperContainer? Does MirrorSync work with that?====<br />
Yes, it does. However, with SuperContainer the approach is very different. Only the URLs are synchronized, not the actual files - they remain on the SuperContainer server. The advantage is syncing is very fast - there is no binary data being transferred. The disadvantage is that you'll only have access to the files stored in SuperContainer when you have working network access from your computer or iOS device.<br />
<br />
====Does MirrorSync sync external container fields?====<br />
Yes, MirrorSync works with external container fields. There are no extra steps to take when syncing with FileMaker Pro or FileMaker Server. If you are using external container fields on an iOS device, there are a few steps after configuration that are required.<br />
<br />
#Download a copy of the database from MirrorSync or FileMaker Admin<br />
#Open the copy on a computer, and navigate to File > Save a copy as...<br />
#Under the type drop down, choose "self-contained copy (single file)"<br />
<br />
This ensures the copy of the file embeds the containers into the file for easy use with FileMaker Go and offline functionality. <br />
<br />
PLEASE NOTE: there is an unfortunate behavior in FileMaker in this process: when saving the self-contained copy, FileMaker updates the modification timestamp for every record that has an external stored container field. That's not a problem normally, but when used with MirrorSync, it will make the initial sync very slow. The reason for this slowdown is due to MirrorSync assuming that all of those records have been modified on the client, so it writes all of the server data to the client (including the container data). <br />
<br />
The workaround for this is to uncheck the modification timestamp auto-entry before saving the self-contained copy, and then turn it back on after the copy has been saved. This modification timestamp behavior has been reported to FileMaker, Inc. and will hopefully be resolved soon.<br />
<br />
====Does MirrorSync require users to sync with full access accounts?====<br />
<br />
No. MirrorSync requires a full access account only once: to paste in the table, scripts, and layout. When users run the sync, they will use their own user account privileges, with whatever access that grants them. See the '[[#Customizing MirrorSync|Customizing MirrorSync]]' section below for tips on restricting user accounts.<br />
<br />
====Does MirrorSync do conflict resolution?====<br />
Yes, MirrorSync has robust conflict detection and field-level merging (added in version 2). It will detect when the same record(s) are modified on both database and take action. There are two settings in the configuration client that will control how this works:<br />
<br />
* <b>Merge the changes together</b>: If MirrorSync sees that all of the changes made in the databases were to different fields (ie. firstName on the server and lastName on the client), it will automatically merge the changes together. It will not tell the user that a conflict occurred, it will just write the merged record to both the server and the client. If any changes were made to the same field, it is treated as a conflict and not merged.<br />
* <b>Flag the edit as a conflict</b>: MirrorSync will treat all modifications to the same record as a conflict, regardless of whether they were made to the same fields or different fields.<br />
<br />
If a conflict occurs, then MirrorSync will resolve it based on the next configuration option:<br />
* <b>User picks:</b> MirrorSync will present a web-based interface to the user, summarizing all conflicts and showing them exactly which fields were changed on both databases. It color-codes the actual sections of text that were changed, making it easy for even inexperienced users to make the best choice. The user is able to pick one entire record over another, pick individual fields from each record, and even manually edit the result to combine changes from both records. They also have the option to automatically select the most recent change (see next option).<br />
* <b>Most recent change wins:</b> MirrorSync will pick whichever record was last modified as the winner of the conflict. If Joe changes a record on his iPad at 3:00 PM, Kate changes the same record on her iPhone at 3:30 PM, and Tom changes the record on the server at 4:00 PM, then when Joe or Kate sync their database, Tom's record will be selected as the winner, regardless of when Joe and Kate do their sync.<br />
* <b>Hub always wins</b>: MirrorSync will always pick the value on the hub (typically FileMaker Server) as the conflict winner, regardless of other considerations. This is not generally recommended, because it is essentially first-sync wins behavior: Whoever syncs to the hub first will win conflicts with other offline users who modify the same record and sync. This setting can be useful if changes made by directly connected users should be given priority over offline, syncing users.<br />
* <b>Email administrator</b>: This is very similar to 'User picks', except that instead of the user who is doing the sync deciding, an e-mail is sent to the administrator email address specified in the configuration. The administrator can resolve the conflict using the same web-based user interface described above, after which the user will be able to sync normally.<br />
<br />
====Is MirrorSync transactional? What happens if the connection is lost while syncing?====<br />
MirrorSync is not 'transactional' in the strictest sense. If the connection is dropped during a sync, it is possible for records from one table to be written to the server, while records from another related table may not be written. However, MirrorSync keeps track of which records have been written and which ones have not, and it will resume from where it was on the next sync and complete everything as if the first sync had finished. If a record on the server cannot be written because it is being edited, the offline user will get a warning error message telling them this. MirrorSync will continue to retry that edit operation each time the sync script is run.<br />
<br />
====Can I use external authentication with MirrorSync?====<br />
Yes, MirrorSync supports externally authenticated accounts with no modifications. So long as the username on the local copy matches the username on the server, you can set up one password for local access and another for external authentication with the server. The passwords do not need to match between the local file and the hosted file.<br />
<br />
<br />
<br />
<br />
=== Server-to-server sync ===<br />
<br />
==== How do I set up server-to-server syncing? ====<br />
For the most part, the process for setting up server-to-client sync is almost identical to server-to-server sync. Here are a few differences to be aware of:<br />
* If you will be syncing container fields across a Wide Area Network (WAN), both servers must have public IP addresses, because they each make HTTP calls to the other.<br />
* In the spoke configuration, you select 'copy or clone of existing file' or 'separate file.' If the first option is selected, you don't actually put the file on the other server during the setup process - go through the setup process, and when you're finished, save a copy or clone from the hub server using the MirrorSync download feature and upload it to the spoke server. If you select 'separate file', then you will need to have the file up and running on the spoke server during configuration.<br />
<br />
==== How do I run a server-to-server sync? ====<br />
You do not use the MirrorSync script from within FileMaker, like a server-to-client sync. Instead, use the 'sync' button in the MirrorSync admin utility. Once you've run the sync and are satisfied that everything is working correctly, you may enable auto-sync by checking that box and specifying the frequency to run the sync.<br />
<br />
==== How can I be notified of a problem that occurs during server-to-server sync? ====<br />
There is an administrative e-mail address that is set during MirrorSync configuration. If you set this, you will receive e-mail notifications whenever the sync fails (or succeeds, depending on what granularity you set admin e-mails to). These e-mails are sent via Amazon Web Services, and thus do not require you to configure an SMTP server.<br />
<br />
===Performance questions===<br />
<br />
====How well does MirrorSync perform on slow networks?====<br />
MirrorSync is very efficient over slow networks, because it sends very little data other than the actual record changes, and it transmits this information in large chunks, which is more efficient. There are 3 HTTP request at the beginning of the sync, and usually 2 HTTP requests per table that contains any modifications. For example, if you have a 20 table solution, and there are changes in 5 of the tables, it will usually take 13 HTTP requests (3 + 2*5) to complete the sync. By comparison, the FileMaker home page takes 65 HTTP requests to load in a web browser.<br />
<br />
<br />
====My file is very large, and I want to give MirrorSync more memory allocation. How do I do this?====<br />
MirrorSync has a 512 megabyte allocation by default. This is typically sufficient for syncing change batches of around 200,000 records, although that number gets much smaller if the records contain a lot of information. Now divide that number by the number of devices simultaneously syncing - so if you expect up to 4 people to be syncing simultaneously, MirrorSync can probably handle up to 50,000 changes from each user with the default memory allocation. If you need more than that, you can increase the memory allocation by modifying the setenv file. Find the 512 and change it some new memory allocation, like 1024. The file is at:<br />
<pre><br />
Mac: /Library/360Works/Applications/bin/setenv.sh<br />
Win: C:\Program Files\360Works\Applications\bin\setenv.bat<br />
</pre><br />
<br />
====What can I do to speed up syncing?====<br />
MirrorSync is pretty fast without any special tweaking, but faster is always better. Here are some tips for squeezing out the best possible sync speed from MirrorSync:<br />
<br />
* SSD drives: MirrorSync does many thousands of tiny read and write operations when syncing large record batches. This type of usage will benefit greatly from the ultra-low latency of SSD drives. You will see a noticeable change in sync speed by installing MirrorSync on an SSD drive. You don't need to use an SSD for your entire hard drive - you can just put MirrorSync on the SSD by using a symbolic link in OS X or changing the install location on Windows. The SSD performance benefits will improve all sync operations, but it will be most noticeable when doing very small syncs with few or no changes, and initial syncs for large database with hundreds of thousands of records.<br />
<br />
* When MirrorSync fetches changed records from FileMaker Server, it requests all changes since 10 minutes prior to the last sync. This 10 minute overlap compensates for users whose clocks are slow. If you're using the Host modification timestamp trick outlined in the timezone section above, then the user clock doesn't matter, and you don't need this 10 minute overlap. You can get rid of it by editing the MirrorSync.xml file and change the 'fmServerOverlapSeconds' parameter from 600 (10 minutes) to 5 (5 seconds). The file is at:<br />
<pre><br />
Mac: /Library/360Works/Applications/conf/Catalina/localhost/MirrorSync.xml<br />
Win: C:\Program Files\360Works\Applications\conf\Catalina\localhost\MirrorSync.xml<br />
</pre><br />
<br />
* Use serial numbers instead of UUIDs, especially for large record sets with narrow tables. The difference between a 5 character serial number and a 36 character UUID adds up, especially when transferring large numbers of records that mostly consist of foreign keys, such as join tables. Don't make this change if you have a good reason for using UUIDs.<br />
<br />
* Container fields hold lots of data, require a guest connection to FileMaker Server over port 5003, and are sent individually instead of in batches like non-container data. If there are containers that you don't need to sync, remove them from the sync layouts. Removing all container fields will give much better sync performance, as well as eliminating firewall concerns, because MirrorSync does not need to connect as a guest of FileMaker Server.<br />
<br />
* If you want to just sync a subset of records, instead of the entire database, you can use either record level access privileges or scripted filters (see the customization section below for more details). Scripted filters are much, much faster then record level access privilege restrictions.<br />
<br />
* If you're on FileMaker 11, switch to 12 or later. All of MirrorSync's communication with FileMaker Server is via the XML Web Publishing Engine, and this was just not very fast in FileMaker Server 11. It is greatly improved in later versions of FileMaker Server.<br />
<br />
* Flag records instead of deleting them: MirrorSync 2 is very fast at detecting deleted records. However, it's always faster to sync edits and inserts than to scan for deletions, especially in large tables with more than 100,000 records. If you want to optimize performance, it might make more sense to flag records as being deleted instead of actually deleting them. That makes it into an edit operation, which is not affected by the number of records in the table.<br />
<br />
===Customizing MirrorSync===<br />
<br />
====I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?====<br />
That's a three-part question with a three-part answer. Just <b>syncing certain tables</b> is very easy: When you're configuring the sync using the MirrorSync configuration utility, only include layouts corresponding to the tables that you want to sync.<br />
<br />
<b>Syncing certain fields</b> is also very easy: Just don't include any fields on your sync layouts except the ones that you want to sync.<br />
<br />
<b>Syncing certain records</b> is only slightly less easy: Edit the 'MirrorSync Customization' script and follow the instructions in the 'FindChanges' documentation there to constrain the found set to just the records you want to sync for the current user. Remember that the script will be running as the user doing the sync, so you can use the Get( AccountName ) function to determine which records are available. <b>Be careful regarding the use of $$globalVariables</b> - they will work correctly for the duration of the current sync, but they will not still be set on the next sync.<br />
<br />
Any records that are excluded by your search criteria will not be synced to the user. In addition, if those records were previously synced, they will be deleted from the user's device. This makes it very easy to create check-in / check-out workflows with MirrorSync, where jobs are synced to iPads, completed, and then deleted from the device.<br />
<br />
To test your customization script, go to the sync layout that you want to test, show all records, and run the MirrorSync customization script. If you don't get the results you expect, use the Script Debugger to tweak it.<br />
<br />
Another approach to limiting record access is with FileMaker's record level access restrictions. Any restrictions you place on the user's privilege set will be respected by MirrorSync, and the user will only receive those records when they do a sync. Records which were previously visible which switch to non-visible will be deleted on the next sync. Keep in mind that scripted record filters will be much faster than using record level access privileges.<br />
<br />
If you decide to limit the synced records, you may choose to distribute an empty clone to your users instead of a full copy of the database. That way, the initial sync will only pull the records into their offline file that they have access to on the database. Keep in mind that if they have access to many thousands of records, that could make the initial sync slower than if you distributed a full copy of the database that already contains all of the record data, and let the initial sync delete the extra records.<br />
<br />
====How can I tell if a record created in FileMaker Go has been synced with the server?====<br />
During configuration, select any field as a write-back value (see [[#writebacks | write-back values]] in the primary key section, above). Make sure that value is only set to auto-enter a value on the server, by checking that <code>Get(MultiuserState) = 2</code>. If the field is blank, the record has not yet been synchronized. If the field contains a value, then it was either created on the server, or created in FileMaker Go and synced with the server.<br />
<br />
Another approach you can take is by modifying the didInsert section of the customization script (see next question), but the write-back approach is significantly faster when syncing.<br />
<br />
====How can I run a script on the server when a record is synchronized?====<br />
Maybe you want to send an e-mail to an administrator when a user completes a delivery, creates a request for a quote, or deletes a job in production. To do these types of operations, modify the MirrorSync customization script. There is a section in the script for 'DidUpdate', 'DidInsert', and 'WillDelete'. Make sure you modify those in the 'Hub' section - it's very rare that these should be modified on the spoke. In the relevant section of the script, check the current layout, and if it's the one where you want to take action, go ahead and do whatever you want in this section. You can freely go to other layouts, do searches / inserts / updates / deletions, send e-mails, or take any other action, as long as you finish the script on the same layout and record where you started.<br />
<br />
If MirrorSync detects that the record was modified as a result of a 'DidInsert' or 'DidUpdate' script, it will re-do the client search, taking into account any scripted record restrictions in the 'FindChanges' section. For example, if you want jobs to be removed from the user's iPad when a record on the 'SyncJob' layout has its status changed to 'Completed', take these steps:<br />
# Modify the 'FindChanges' to exclude records whose status is 'Completed' when Get(LayoutName) = "SyncJob". (To do this type of search in FileMaker, enter Find mode, Set the status field to 'Completed', Omit the current record/request, and then Constrain Found Set)<br />
# Modify the 'DidInsert' section to blank out the modification timestamp when Get(LayoutName) = "SyncJob".<br />
# Do the same thing in the 'DidUpdate' section.<br />
<br />
Now, whenever an offline user updates or inserts a record in the 'SyncJob' table, the script will blank out the modification timestamp. This triggers a change, which causes MirrorSync to re-do the search, which will exclude the complete job from the search, which will automatically remove it from the iPad.<br />
<br />
You might ask, why blank out the modification timestamp? The answer is that it actually doesn't matter what you do, as long as you make some change to the record at all. Blanking out the modification timestamp is a harmless change, because FileMaker will immediately replace the blank value with a new timestamp. You could just as well set any field on the record to its current value, or make some more meaningful change, such as filling in a date field with the data that the job was completed.<br />
<br />
====I don't want users to see any dialogs when the sync runs, can I prevent them from showing?====<br />
Yes, set the global variable $$SILENT_MODE to "1" in the MirrorSync customization script. This will prevent MirrorSync from showing any dialogs unless an error occurs, and for required information like login and conflict resolution.<br />
* If you would like to also skip the login dialog, AND if you know the user's password (ie. if it's stored in a users table) OR everybody is syncing with the same account, you can hard-code the $$MIRRORSYNC_USERNAME and $$MIRRORSYNC_PASSWORD values in the MirrorSync customization script. If these are both non-empty values, then MirrorSync will not prompt the user to enter their password.<br />
* If you would like to prevent the conflict resolution dialog from displaying, pick any option other than 'user decides' in the conflict resolution section of the MirrorSync configuration process.<br />
<br />
==== I don't want users to see the MirrorSync window at all when a sync runs. Can I prevent that from showing? ====<br />
If you are running MirrorSync on FileMaker Pro, then yes. Set the $$MIRRORSYNC_HIDE_WINDOW variable to 1 in the MirrorSync customization script. This will move the MirrorSync window off-screen, where the user cannot see it. This is not recommended for large sync operations that will take longer than a few seconds, because without that status display, users may think that their computer is frozen.<br />
<br />
If you are running MirrorSync on iOS, then this cannot be hidden. That is because MirrorSync needs to open a new window to manipulate the found set without losing the current selection, and new windows cannot be hidden offscreen on iOS devices. The $$MIRRORSYNC_HIDE_WINDOW variable will be ignored on iOS.<br />
<br />
==== Can I block other MirrorSync dialogs from being displayed to the user, or change the wording? ====<br />
Yes. Using the MirrorSync customization script, all dialogs, even error messages, can be suppressed or modified. Look towards the bottom of the MirrorSync customization script, and you will see a section that includes a dialog for each type of message that is displayed to users during a normal sync. You may freely customize the message displayed to the user, or the title of the buttons (but be sure that the first button still has the same meaning, and the second button still has the same meaning). If you want to hide the dialog from showing, you can disable the script step that displays it, but you must decide which option you would like to select, and exit the script with that button number. You can use this technique to display messages to your users in their preferred language.<br />
<br />
====Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?====<br />
Yes, absolutely. First of all, we recommend setting the 'MirrorSync setup' script as your startup script, or calling it from the startup script. This will check to see if the file is running offline, and whether it has ever been synced before. If not, it will prompt the user to do the initial sync. In addition, the MirrorSync setup script sets the $$MIRRORSYNC_CLIENTID global variable, which is necessary for some primary key strategies ([[#Primary key / serial numbers |see the Primary Key section above]]).<br />
<br />
Remember that the MirrorSync script is a regular FileMaker script that can be set to run at any time by the developer. For example, if there is a critical section of your application that requires users to see what the latest value is before they make a change, trigger the sync when the user navigates to that screen, and again when they are finished editing in that screen. You could make it so that checking a box, clicking a button, or any other condition that you choose can trigger the sync to happen.<br />
<br />
====Can MirrorSync run automatically every x seconds/minutes?====<br />
Yes, you can use an On Timer script to trigger this. However, keep in mind that when the script runs, it commits the current record and pops open a new window that could be open for a few seconds or longer. This could get annoying if it happens in the middle of something that the user is working on. For this reason, we recommend the approach in the previous question of linking your script sync operations to some user-initiated action. The exception to this is unattended computers - if you want to have a computer that is running MirrorSync all the time for purposes of having an extra copy of the database replicated, without a user working on it, then by all means go ahead and use an On Timer script step (and be sure to see [[#I don't want users to see any dialogs when the sync runs, can I prevent them from showing?|the FAQ above about]] disabling dialogs).<br />
<br />
==== Customizing the MirrorSync layout ====<br />
Feel free to make cosmetic changes to the 'MirrorSync' layout that is pasted into your solution. However, follow these tips before making changes:<br />
* Make sure you are able to successfully sync on FileMaker Pro and FileMaker Go before making customizations.<br />
* Make a backup copy of the unmodified MirrorSync layout first.<br />
* It is important that you preserve the tabs on the layout, and that the same fields remain in those tabs. The other thing to be careful about is that there are two 1x1 pixel web viewers on the MirrorSync layout. Make sure that those remain visible on the layout.<br />
* If the sync stops working after you make the changes, then you may have inadvertently lost the web viewers on the layout. Restore them from the backup copy of the layout.<br />
<br />
=== Licensing ===<br />
<br />
==== How does licensing and pricing work for MirrorSync? ====<br />
MirrorSync is completely free to use, with no limitations on features, for syncing FileMaker Server with a single copy of FileMaker Pro or FileMaker Go. You can optionally purchase additional server configurations or devices.<br />
<br />
The supported configuration types are:<br />
* FileMaker Server with FileMaker clients (Go or Pro)<br />
* FileMaker Server with FileMaker Server<br />
* FileMaker Server with any SQL database (Oracle, MySQL, and MS SQL Server are fully supported. You may also sync with any database with a JDBC driver).<br />
* SQL database with SQL database<br />
* SQL database with FileMaker clients (Go or Pro)<br />
<br />
Devices are sold in quantities of 1, 5, 10, 40, and unlimited. These can be purchased in addition to the single device that comes with MirrorSync for free.<br />
<br />
==== Is MirrorSync included in the 360Works Portfolio Bundle?====<br />
Yes. MirrorSync 2 is free, but Portfolio Bundle (http://360works.com/portfolio) subscribers will receive an additional 10 device pack. There is also a special licensing program for FileMaker Business Alliance (FBA) members; contact us at support@360works.com for details.<br />
<br />
==== Is there a vertical market license type for MirrorSync? ====<br />
Yes. Contact support@360works.com for details about how this works.<br />
<br />
=== Miscellaneous questions ===<br />
<br />
====Is MirrorSync localized into any non-English languages? Does it work in other languages?====<br />
At this time, MirrorSync is only localized to English. Our current focus is on adding features, but we anticipate translating this into other languages when the product is more mature. If you would like to offer help with translation, please contact support@360works.com to let us know. You should still be able to add MirrorSync to your solution in other languages. See the previous section on customizing dialogs for tips on localizing your solution.<br />
<br />
====I only have an offline copy of my file left, and need to upload it back to the server. What do I do?====<br />
If necessary, you can re-upload an offline copy of the file to FileMaker Server and use it with MirrorSync. <b>Be sure to remove the "Client" record in the MirrorSync table</b>, and keep only the "Server" record. To do this, navigate to the MirrorSync layout, switch to the Debugging tab, and perform a find for "Server" in the type field. Select the inverse of the records found by pressing the pie icon in the status bar. Then, delete those other records.<br />
<br />
=== Troubleshooting/Known Issues ===<br />
<br />
==== The maximum number of users are currently using this copy of FileMaker Pro====<br />
<br />
[[File:MirrorSyncLicense.png|thumb|Example of error message]]<br />
<br />
There is a bug in FileMaker Pro and FileMaker Pro Advanced that may occur when pasting the MirrorSync script, or editing the MirrorSync script. This occurs due to the references found in the script, which will reference both the internal and external IP address. FileMaker then opens both of those references, which triggers the licensing server as two copies of FileMaker Pro. This error would occur for any script that contains both references to a single hosted file. <br />
<br />
There are two work arounds for this:<br />
<br />
# Upgrade your single user license to a volume license. You can contact FileMaker directly to upgrade your license if you have 5 or more copies.<br />
# Paste the script and let FileMaker close due the licensing error. The script will save appropriately, and should work correctly.<br />
<br />
If you require assistance on this issue, please let us know.<br />
<br />
====I keep getting a 102 'Field is missing' error, but I know my Sync layouts have all the right fields, what's wrong with it?====<br />
Make sure that the sync layouts are matching in both the offline and server copy. If you have repeating fields, make sure the fields show the maximum number of repetitions that are defined in the field definitions. In other words, if a field can repeat 5 times, make sure the repetitions in the inspector show 5.</div>Sarahhttp://docs.360works.com/index.php/MirrorSync_2_basic_setupMirrorSync 2 basic setup2013-12-11T18:55:19Z<p>Sarah: Created page with " ==Overview== MirrorSync is an elegant synchronization product that can sync between any combination of FileMaker Pro, FileMaker Go, FileMaker Server, or SQL database (MySQL, ..."</p>
<hr />
<div><br />
==Overview==<br />
MirrorSync is an elegant synchronization product that can sync between any combination of FileMaker Pro, FileMaker Go, FileMaker Server, or SQL database (MySQL, Oracle, SQL Server, or any database that supports JDBC). For mobile devices, users can sync the hosted file with their FMGo or Pro clients, go off network to make changes, and sync again when a connection is available. For servers, MirrorSync allows a database to run in multiple locations, or to integrate different databases and make sure that changes to each server are reflected in the other server.<br />
<br />
MirrorSync is only installed on the server computer. It is not a plug-in, and does not require any software installation on client devices.<br />
<br />
MirrorSync is extremely easy to set up. The only changes you will need to make to your database are:<br />
# Enabling the FMXML extended privilege in your security configuration.<br />
# Making sure that every table you want to sync has a primary key, modification timestamp, and creation timestamp.<br />
# Creating a layout for each table.<br />
# Four copy and paste operations.<br />
<br />
==Why use MirrorSync?==<br />
# For mobile users who access the database with FileMaker Go on their iOS device, MirrorSync allows these users to work efficiently with limited or no connectivity to the server network. Each user can take a local copy on their iPad or iPhone, input the information from the field, and then sync when they regain a network connection. Depending on their workflow, they could even specify a one-way sync where their information is pushed to the server, but no data is pulled down, or vice versa for users who need fast read-only information.<br />
# For remote users who work on laptops, MirrorSync solves the problem of how to work productively on a hosted FileMaker database, regardless of network speed. If, for example, you have multiple users connecting to FileMaker Server over a wide area network (WAN) you could notice a substantial slowdown, as every change is immediately written back to FileMaker Server. MirrorSync allows each user to take a local copy of the database which would run on the users machine and not be affected by the WAN performance. The user could sync when they first came into the office, work on their local copy throughout the day, and sync at specified times (or on demand) to push and pull the latest data to the server.<br />
# For groups of users at multiple locations, MirrorSync should be used in server-to-server mode, where an identical copy of the database is installed on FileMaker Server in each location. Each workgroup works at full LAN speed on their own FileMaker Server, and MirrorSync takes care of keeping the servers in sync with each other, so that each workgroup can see and edit changes made by the other group. In this configuration, MirrorSync should be set to sync very often, such as every 30-60 seconds.<br />
# For integration with non-FileMaker databases, MirrorSync is the simplest and most efficient way to accomplish this. For instance, if you have an online storefront running with MySQL or Oracle at a remote data center, but you need to have instant access to all of the orders in a database running on FileMaker Server, MirrorSync can selectively sync certain SQL tables to FileMaker, even if the table and field names do not match. In this configuration, MirrorSync should be set to sync fairly often, such as every 5-10 minutes.<br />
<br />
<br />
<br />
== Requirements ==<br />
* Server:<br />
** Windows 2003r2 or later, or Mac OS X 10.5 or later<br />
** FileMaker Server 11.0v3, 12, or 13, with XML Web Publishing enabled.<br />
** 3 gigabytes or more of RAM. 8 gigabytes or more are recommended for large databases with hundreds of thousands of rows, or for more than 10 simultaneous sync operations.<br />
* Configuration utility (only run by developer / administrator):<br />
** OS X 10.6 or later, or Windows 2007 with Java 1.6 or higher installed<br />
** FileMaker Pro 11, 12, or 13 (FileMaker Pro Advanced is recommended and reduces setup steps, but not required. If you do not have FileMaker Pro Advanced, read [[MirrorSync_advanced_topics#Configuration_without_FileMaker_Pro_Advanced|the FAQ on Is FileMaker Pro Advanced necessary for configuration?]]. Configure MirrorSync using the FileMaker Pro version the FileMaker Server is using- ie, use FileMaker 12 for FileMaker 12 Server for the initial configuration.<br />
* Sync Client:<br />
** Mac or Windows with FileMaker Pro 11, 12, or 13 OR<br />
** FileMaker Go (any version) running on iPad, iPhone, or iPod Touch<br />
<br />
==MirrorSync With Hosting Providers==<br />
<br />
MirrorSync supports hosting provider installations of MirrorSync.<br />
<br />
The following companies have indicated that they are set up or willing to configure their servers to host MirrorSync. If you'd like to be added to this list, please contact us at plugins@360works.com.<br />
<br />
* '''ODI Technologies''' ( http://www.oditech.com/ )<br />
* '''Michael Tinder, DataUp365''' ( http://dataup365.com/DU/ )<br />
* '''John May, Point in Space''' ( http://www.pointinspace.com/ )<br />
* '''Andrew McCallum, Niche IT Pty Lty''' ( http://www.nicheit.com.au/ )<br />
* '''Foxtail Technology''' ( http://www.foxtailtech.com/ )<br />
* '''NeoCode Software''' ( http://www.neocodesoftware.com )<br />
* '''WorldCloud''' ( http://www.worldcloud.com )<br />
* 360Works can also host your database with MirrorSync, so [mailto:infobox@360works.com please contact us directly] about this service.<br />
<br />
If you are a hosting provider, read the [[MirrorSync_advanced_topics#Installation_for_hosting_providers | Installation for hosting providers]]' section in the advanced documentation page.<br />
<br />
==Technical overview==<br />
MirrorSync is a web application, installed on a server (typically on FileMaker Server) and accessed on client machines through a FileMaker Web Viewer and the Insert from URL script step. MirrorSync communicates with FileMaker Server using the XML Web Publishing Engine.<br />
<br />
For FileMaker Pro/Go sync, users run the sync by triggering a regular FileMaker Script in the solution. For server-to-server sync, the syncs are run using the MirrorSync admin utility, and can be scheduled to run in the background at regular intervals.<br />
<br />
There are no plug-ins or other software to install on user's devices. Java is not a requirement except for the server and for the developer configuration.<br />
<br />
For server-to-server sync, all communication is done via the XML Web Publishing Engine, or via JDBC (for non-FileMaker databases).<br />
<br />
== Three ways to get started with MirrorSync ==<br />
We've setup three ways for you to try MirrorSync:<br />
# <b>Live demo (time to sync: Less than 1 minute)</b>: If you would like to see MirrorSync in action without even needing to install anything, you can download our live MirrorSync demo database from [http://sync.360works.com/MirrorSync/dbDownload/e5a1eaed-43c4-40f8-a704-ffa803df764a here]. Just open the file in FileMaker Pro or Go, make some changes, and then hit the sync button. To see how MirrorSync works between multiple devices, use that same download URL on a different device and sync away! Be aware that the data in this file is shared with everybody who downloads it, and also that it resets every night at midnight EST, so don't put anything important in this file.<br />
# <b>Sync using the Tasks template (time to sync: Approximately 20 minutes)</b>: Using the tasks starter solution that comes with FileMaker Pro, we provide a step-by-step video walkthrough that you can follow along with. This 13 minute video starts with creating a new FileMaker database and goes through setup and sync. Just watch the video for each step, and pause while you do it on your own file. [http://www.youtube.com/watch?v=quqy-aXQ2xA&feature=youtu.be Watch the video on YouTube].<br />
# <b>Configure your own file for syncing (time to sync: 30-90 minutes for most solutions)</b>: Follow the instructions below to configure MirrorSync with your own FileMaker solution.<br />
<br />
== Installing / upgrading ==<br />
MirrorSync has a standard OS X and Windows installer included with it. Just double-click the installer for your platform and follow the instructions. Be aware that if you re-install FileMaker Server at some point in the future, you may need to re-run the MirrorSync installer in order to set the web server settings correctly.<br />
<br />
If you are upgrading from MirrorSync 1, be aware that existing configurations will not be preserved, and must be re-created. Offline users will not be able to sync with their old offline files, so they should sync any unsaved changes before proceeding. Your existing sync layouts can still be used with MirrorSync 2, with one change: You must include a creation timestamp field on the layout, in addition to the required fields for version 1. Read the [[MirrorSync_advanced_topics#upgradeFrom1|upgrading section]] in the advanced documentation for more details.<br />
<br />
== Preparing your database for use with MirrorSync ==<br />
<div id="multifile"></div><br />
* MirrorSync only supports sync with a single-file database, so if you have a multi-file solution (ie. separation model or migrated from older FileMaker version), make sure that there is a single main file with external table occurrences referencing the other files. When you distribute offline files to your users, you will distribute the entire set of files, which will include the main sync file.<br />
<div id="XMLpriv"></div><br />
* Be sure that the XML extended privilege is enabled in FileMaker Pro for all accounts that will use MirrorSync. Choose this option under File > Manage > Security… Double click the FileMaker user, and choose Edit… from the Privilege Set.<br />
<div id="primarykey"></div><br />
* Make sure that every table in your solution has a primary key. This is a unique identifier which cannot be empty, and should never be changed once the record is created. MirrorSync can work with traditional serial number primary keys, UUID primary keys, or custom primary key strategies. It will save steps during setup (but it's not required) for your primary keys to have the 'not empty' validation option enabled. Also, if you are using UUID primary keys, be sure to <b>UNCHECK</b> the field options checkboxes that say 'Do not replace existing value of field' and 'Prohibit modification of value during data entry'. For a deeper discussion of how primary keys are handled when syncing, refer to '[[MirrorSync_advanced_topics#Primary_key_.2F_serial_numbers|Primary key considerations]]' in the advanced documentation.<br />
* If your solution uses serial numbers as user-visible data for things like job numbers, check numbers, P.O. numbers, or invoice numbers, refer to the section '[[MirrorSync_advanced_topics#What_if_I_need_to_assign_a_user-friendly_serial_number_to_my_records_that_stays_the_same_when_it_is_synced.3F_For_example.2C_an_invoice_number.3F|User-visible serial numbers]]' in the advanced documentation.<br />
<div id="timestamps"></div><br />
* Every table (including join tables) must have a timestamp field which is set to auto-enter a modification timestamp, as well as a creation timestamp field which auto-enters the creation timestamp. If you will have users with direct, online access to FileMaker Server who are <i>not in the same time zone as the FileMaker Server</i>, you will need to set up special host modification timestamps as outlined in the '[[MirrorSync_advanced_topics#Does_MirrorSync_work_with_timezones.3F |Time zone considerations']] section of the advanced documentation. This requirement does not apply to offline users in different time zones, who access the server via MirrorSync.<br />
* Please remove or rename fields that have parentheses ( ) or square brackets [ ] in the name. These fields are incompatible with MirrorSync.<br />
* Host the database on FileMaker Server. Open the file from the server with FileMaker Pro Advanced, using a full access account. If you do not have FileMaker Pro Advanced, refer to the '[[MirrorSync_advanced_topics#Configuration_without_FileMaker_Pro_Advanced|Configuration without FileMaker Pro Advanced']] section in the advanced documentation.<br />
<br />
== Integrating MirrorSync into your solution ==<br />
<div id="install"></div><br />
Here are the steps to integrate MirrorSync into your solution:<br />
# Install MirrorSync. You can install MirrorSync anywhere, although the easiest option is to install it on your FileMaker Server. During installation, you will create a username and password that will be used to administer MirrorSync.<br />
# After installation, you will be taken to the MirrorSync home page. This is located at http://yourServerAddress/MirrorSync, or in some cases, http://yourServerAddress:42424/MirrorSync. Keep in mind that you can open this page and proceed with the rest of the integration process from your own computer - you don't need to do the entire process from where you have MirrorSync installed. From the home page, click the blue 'Launch MirrorSync Client' button. If you are using Mac OS X, you will then need to double-click the downloaded JNLP file.<br />
# Use the username and password you created during setup to log in to the config client, and then follow the setup instructions in the config client.<br />
# After completing the setup, if you will be syncing with FileMaker Pro or Go, you will need to distribute offline copies of your solution to your users. Click the 'Download Database' button in the config client and choose either 'Download' for quick testing on your own computer, or 'Create Link' for deployment to end users.<br />
# Once you have created an offline copy, run the 'MirrorSync' script to do the initial sync, and then run it again whenever you want to sync with the server. If you'd like to, you can add a button somewhere on the layout for users to run the sync easily.<br />
<br />
== Distributing new versions of your application ==<br />
When you make development changes to the file hosted on FileMaker Server, as long as you do not delete or rename fields, it will not interfere with offline user's ability to sync. You can add new tables, layouts, fields, scripts, etc., and your existing offline files will continue to sync normally.<br />
<br />
Once you are ready to deploy your changes to offline users, edit the configuration in the MirrorSync admin utility. When you get to the end of the process, re-copy and paste the script steps into your FileMaker solutions. Send an e-mail to your users with a download link (you can use one you've generated in the past or create a new one) and instructions to sync their old file, delete it, and then download a new one. Users who do not download the file will also continue to sync normally, they just won't have the latest and greatest version of the solution.<br />
<br />
== Advanced topics ==<br />
This document should get you up and running with MirrorSync. However, there are many advanced features and customizations available, which are covered on the [[MirrorSync advanced topics]] page.<br />
<br />
== Getting help ==<br />
If you encounter an unexpected error message when syncing, please go to the MirrorSync homepage and click the link titled 'report a bug'. This will send us the sync log file, which is required to solve almost all issues. Be sure to include your contact info in the bug report so that we can get in touch with you.<br />
<br />
There is an [http://fmforums.com/forum/forum/172-mirrorsync-by-360works/ online discussion forum] hosted by FMForums. Please look through the posts and see if your question has been posted before making a new topic.<br />
<br />
If you have other questions, we have a dedicated support team that is ready to help. Send us an e-mail at support@360works.com or call us at 866-662-9185.</div>Sarahhttp://docs.360works.com/index.php/MirrorSync_3MirrorSync 32013-12-11T18:54:51Z<p>Sarah: Created page with "{| cellpadding="10" style="margin: 1em auto 1em auto;" |- | colspan="2" | <center><big>Which docs do you need?</big></center> |- | style="border: 1px solid darkgray;vertica..."</p>
<hr />
<div>{| cellpadding="10" style="margin: 1em auto 1em auto;" <br />
|- <br />
| colspan="2" | <center><big>Which docs do you need?</big></center><br />
|- <br />
| style="border: 1px solid darkgray;vertical-align:top;" | <span style="font-size:175%">[[MirrorSync basic setup]]</span> <p>Everybody who uses MirrorSync should read this section.</p><br />
| style="border: 1px solid darkgray;" | <span style="font-size:175%">[[MirrorSync advanced topics]]</span> <p>You should read this section if you:</p><br />
* Are a hosting provider<br />
* Want to customize the behavior of MirrorSync<br />
* Want to optimize the performance of MirrorSync as much as possible<br />
* Are getting an error message and want to check if it's a known issue<br />
* Are just curious!<br />
<br />
|}</div>Sarahhttp://docs.360works.com/index.php/Web_Services_Manager_installationWeb Services Manager installation2013-12-03T22:11:02Z<p>Sarah: Updated for 13</p>
<hr />
<div>Once you have installed Web Services Manager correctly, head back to the [[WebServicesManager]] documentation for more information.<br />
<br />
=== Conceptual Overview ===<br />
Web Services Manager exposes your FileMaker scripts as SOAP Web Services. You use a FileMaker-based control panel to configure which scripts should be exposed, how parameters should be passed to them as input, and which fields will be returned as the output.<br />
<br />
Once you have installed and configured Web Services Manager, any SOAP compatible software (such as Java, .NET, PHP, Ruby, Python, C++, or FileMaker itself using the Nexus Web Services plugin - http://www.fmnexus.com/products/webservices/ ) will be able to trigger FileMaker scripts without having to know anything about FileMaker Pro. The SOAP Web Services published by the Web Services Manager are indistinguishable from any other SOAP server.<br />
<br />
Web Services Manager is designed with performance and scalability in mind. It triggers scripts by communicating directly with the FileMaker Web Publishing XML gateway, bypassing intermediary layers such as the FileMaker PHP API or FX.PHP. Because of this, there is no maximum limit on the number of records that can be returned by the FileMaker script.<br />
<br />
=== System Requirements ===<br />
* You must be running FileMaker Server or Server Advanced with version 9 or later.<br />
* The Web Publishing Engine must be enabled<br />
<br />
=== Installation ===<br />
# Deploy the 'Web Services Manager.fp7' and 'WSM Examples.fp7' files onto your FileMaker Server, as you would any normal FileMaker database.<br />
# Open the database 'Web Services Manager' as a guest of the FileMaker Server. The username and password are user/pass. You will need to change the password to something else; be sure to keep a record of the new password.<br />
# After you change the password, edit the 'websvcmgr.php' file and change line 10 of that file to reflect the new password.<br />
# Copy the 'websvcmgr.php' file into your Web Server document root, where you would normally put PHP files for use with the Web Publishing. On OS X, this defaults to '/Library/WebServer/Documents. On Windows, this defaults to 'C:\Inetpub\wwwroot'<br />
<br />
Follow the steps in the 'Getting Started' tab to start using Web Services Manager. Start with the section 'Required configuration'.<br />
<br />
=== For FileMaker Server 13 ===<br />
<br />
FileMaker Server 13 overrides the typical location for Library/WebServer/Documents or C:\Inetpub\wwwroot. Instead you should copy the PHP file to '''FileMaker Server/HTTPServer/htdocs/'''<br />
<br />
===Troubleshooting===<br />
Make sure to use the correct IP or domain name.</div>Sarahhttp://docs.360works.com/index.php/FirstDataFirstData2013-11-08T17:45:32Z<p>Sarah: Added detailed instructions for certificate handling</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==First Data==<br />
<br />
First Data can process a wide variety of transactions, including card swipes, eCheck / ACH payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [https://www.firstdata.com/en_us/home.html First Data Gateway], and use your '''user ID''' and the '''password''' as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of user ID and password. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
userID;<br />
password; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. If you have a card present account, pass in cardPresent=true.<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("First Data"; "cardPresent=true")]</pre><br />
<br />
'''Returns''': 1 if a valid gateway is provided, ERROR otherwise.<br />
<br />
As a First Data customer, you'll be supplied with a security certificate. You can find this certificate in the Support Center, under downloads when logging in to your account. The download will contain several files, including the auth.txt which will contain your user name and password you use with the plug-in functions. Find the .ks file and place it in a container in your solution. This is your certificate you'll need to work with First Data. The password to use the certificate will be found in the .ks.pw.txt file. Call the <code>CCSetCertificate</code> function and specify the container and the password from the .ks.pw.txt file:<br />
<br />
<pre>Set Variable [$cert; Value:CCSetCertificate ( certificate ; password )]</pre><br />
<br />
'''Returns''': 1 if a valid certificate is provided, ERROR otherwise.<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
{{Template:Processing Payments|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
=== Processing ACH payments ===<br />
<br />
{{Template:Processing ACH payments|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
<pre>Set Variable $result Value:<br />
CCProcessAuthorizedPayment(<br />
userID,<br />
password;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre><br />
<br />
The dollarAmount is not required to process the authorized payment.<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
userID;<br />
password;<br />
chargeAmount;<br />
"";<br />
"";<br />
"swipe=%B1234123412341234^LAST/FIRSTM^1112101000000000011100111000000?;1234123412341234=11121010000000000111?")]<br />
</pre><br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|userID|password}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with First Data, pass in the blank transaction ID. It will be a little different based on whether it was a swiped or a typed card:<br />
<br />
{|<br />
<br />
|-<br />
<br />
|''Card Not Present Unlinked Refund''<br />
<br />
|''Card Present Unlinked Refund''<br />
|-<br />
| <pre>Set Variable $result Value:<br />
CCRefund(<br />
userID,<br />
password;<br />
"";<br />
cardNumber;<br />
amountToCredit;<br />
"expirationDate=12/13")<br />
</pre><br />
<br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
userID,<br />
password;<br />
"";<br />
"";<br />
amountToCredit;<br />
"swipe=")<br />
</pre><br />
<br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
First Data supports all five subscription functions. Creating and modifying subscriptions all accept the same optional parameters, available in the table below.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use CCCreateSubscriptionACH. Do not pass in a subscription name. You'll also need to set a maximum number of failures using the key=value syntax.<br />
<br />
Valid pay periods may include monthly, yearly and the like. Frequency indicates how often in that period. For example, a biweekly subscription would have a pay period of weekly and a frequency of 2. The number of installments specify how many transactions to run total.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big><br />
| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|userID||userID<br />
|-<br />
|password||password<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||"";<br />
|-<br />
|payPeriod||"";<br />
|-<br />
|frequency||"";<br />
|-<br />
|"maximumFailures="||numberOfInstallments<br />
|-<br />
|||startDate<br />
|-<br />
|||payPeriod<br />
|-<br />
|||frequency<br />
|-<br />
|||"maximumFailures="<br />
|-<br />
|||"driversLicenseNumber="<br />
|-<br />
|||"driversLicenseState<br />
|}<br />
<br />
'''Returns''': a subscription ID if the subscription has been successful, "ERROR" if there was a problem.<br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big><br />
| <big>CCModifySubscriptionACH</big><br />
|-<br />
|userID||userID<br />
|-<br />
|password||password<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|dollarAmmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||"";<br />
|-<br />
|payPeriod||"";<br />
|-<br />
|frequency||"";<br />
|-<br />
|"maximumFailures="||numberOfInstallments<br />
|-<br />
|||startDate<br />
|-<br />
|||payPeriod<br />
|-<br />
|||frequency<br />
|-<br />
|||"maximumFailures="<br />
|}<br />
<br />
Modifying and creating subscriptions accepts the following:<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|userID<br />
|-<br />
|password<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/Template:Plugin_BasicsTemplate:Plugin Basics2013-11-08T16:51:55Z<p>Sarah: /* Error Handling/Reporting */</p>
<hr />
<div>====Requirements====<br />
<br />
FileMaker 7 or higher, Java Virtual Machine (JVM) 1.5 or higher, Windows or Mac OS X 10.4. Rosetta on Intel Macs not supported.<br />
<br />
====Installation====<br />
<br />
To install the plug-in, copy the plug-in to the correct directory:<br />
<br />
''FileMaker Pro'': FileMaker / Extensions<br /><br />
''Web Publishing Engine'': FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins *<br /> <br />
''Custom Web Publishing'': FileMaker Server/Web Publishing/publishing-engine/cwpc/Plugins *<br /><br />
''Mac FileMaker Server Scheduled Scripts'': /Library/FileMaker Server/Database Server/Extensions *<br /><br />
''Windows FileMaker Server Scheduled Scripts'': C:\Program Files\FileMaker\FileMaker Server\Database Server\Extensions *<br /><br />
<nowiki>* (Requires Enterprise license)</nowiki><br />
<br />
Create the "Plugins" folder if it doesn't exits. Make sure to restart FileMaker Pro / Server / WPE. Enable the plug-in in FileMaker Server Admin console for scheduled scripts on the server. For users running 64-bit versions of Windows and FileMaker Server 12.02 and later, use the 64 bit version of the plug-in in the custom web publishing location ''only.'' The 64 bit plug-in is marked with .fmx64<br />
<br />
====Uninstalling the plug-in====<br />
<br />
Uninstall the plug-in by quitting FileMaker Pro or stopping FileMaker Server and removing the plug-in file from your Extensions directory.<br />
<br />
====Demo mode and registering the plug-in====<br />
<br />
Plug-ins will run in a fully featured demo mode until they are registered. While running in demo mode, the product will run for 2 hours every time you launch FileMaker / FileMaker Server / FileMaker Web Publishing Engine until restarted. Enter the license information in FileMaker Preferences, or by using a script and calling <code>CCRegister</code>.<br />
<br />
Set Variable [ $register Value:<br />
CCRegister ( licenseKey, registeredTo)<br />
<br />
'''Returns''': a 1 on success or a 0 on failure.<br />
<br />
====Error Handling/Reporting====<br />
<br />
When something unexpected happens, the plug-in will pop up a dialog showing what the error message is. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call <code>CCSetErrorCapture</code> with a parameter of true. That will suppress the error dialog from appearing to the user.<br />
<br />
Whether or not you suppress the error dialogs, a plugin function will return the word <code>ERROR</code> if something goes wrong. It's a good idea to put your plugin functions in an 'If' statement so that you don't execute a bunch of script steps after something has gone wrong. If you'd like for your script to get the error message, you can get that by calling the <code>CCLastErrror</code> function. For example:<br />
<br />
<pre><br />
Set Variable [ $result = MyPluginFunction("x" ; "y" ; "z") ]<br />
If [ $result = "ERROR" ]<br />
Show Custom Dialog [ "An error occurred: " & CCLastError ]<br />
End If<br />
</pre><br />
<br />
If a plug-in is not installed correctly, calls to a plug-in function will return "?"<br />
<br />
=====To check if a transaction succeeded=====<br />
<br />
The simplest way to check to see if money has changed hands in a payment processing function call is to check the result of the function itself. This is extremely useful when calling <code>CCProcessPayment, CCVoid, CCRefund,</code> and others. The result of the transaction will give a transaction ID or the word ERROR. Using the <code>CCLastError</code> like in the example above will give further information about the error, such as if there is no network connectivity, or the card was declined. <br />
<br />
Set Variable[$result ; CCProcessPayment(...)]<br />
If[$result = "ERROR"]<br />
#Transaction is unsuccessful. Below is an example of how you might handle the error. <br />
Set Field[Transaction::Error Message ; CCLastError]<br />
Else<br />
#Transaction is successful.<br />
Set Field[Transaction::Transaction ID ; $result]<br />
End If<br />
<br />
'''More Information'''<br />
<br />
For more information on how to correctly install and work with plug-ins, check out the [[Plugins 101]] documentation.</div>Sarahhttp://docs.360works.com/index.php/Template:Getting_informationTemplate:Getting information2013-11-07T21:02:46Z<p>Sarah: </p>
<hr />
<div>Plastic includes a number of helper functions that allow users to retrieve data from the gateway or Plastic. <br />
<br />
To execute any of these functions inside of a script, use a Set Field or Set Variable script step.<br />
<br />
* '''CCGetCardIssuer'''(''cardNumber'') - returns the card issuer for a given card number, either: VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB. Returns an error if the card number is from another issuer.<br />
* '''CCGetLast''' (''name'') - returns a value from the most recent transaction response that corresponds with the name parameter.<br />
* '''CCLastAVS'''- returns the gateway's Address Verification System Response for the last payment which was processed. This response is typically a one letter indicator, meaning the following:<br />
{| class="wikitable"<br />
|-<br />
! Code<br />
! Description<br />
! Network<br />
|-<br />
| A<br />
| Street address matches, but 5-digit and 9-digit postal code do not match.<br />
| Standard domestic<br />
|-<br />
| B<br />
| Street address matches, but postal code not verified.<br />
| Standard international<br />
|-<br />
| C<br />
| Street address and postal code do not match.<br />
| Standard international<br />
|-<br />
| D<br />
| Street address and postal code match. Code "M" is equivalent.<br />
| Standard international<br />
|-<br />
| E<br />
| AVS data is invalid or AVS is not allowed for this card type.<br />
| Standard domestic<br />
|-<br />
| G<br />
| Non-U.S. issuing bank does not support AVS.<br />
| Standard international<br />
|-<br />
| I<br />
| Address not verified.<br />
| Standard international<br />
|-<br />
| M<br />
| Street address and postal code match. Code "D" is equivalent.<br />
| Standard international<br />
|-<br />
| N<br />
| Street address and postal code do not match.<br />
| Standard domestic<br />
|-<br />
| P<br />
| Postal code matches, but street address not verified.<br />
| Standard international<br />
|-<br />
| R<br />
| System unavailable.<br />
| Standard domestic<br />
|-<br />
| S<br />
| Bank does not support AVS.<br />
| Standard domestic<br />
|-<br />
| U<br />
| Address information unavailable. Returned if the U.S. bank does not support non-U.S. AVS or if the AVS in a U.S. bank is not functioning properly.<br />
| Standard domestic<br />
|-<br />
| W<br />
| Street address does not match, but 9-digit postal code matches.<br />
| Standard domestic<br />
|-<br />
| X<br />
| Street address and 9-digit postal code match.<br />
| Standard domestic<br />
|-<br />
| Y<br />
| Street address and 5-digit postal code match.<br />
| Standard domestic<br />
|-<br />
| Z<br />
| Street address does not match, but 5-digit postal code matches.<br />
| Standard domestic<br />
|}<br />
* '''CCLastCCV'''- returns the gateway's Card Code Verification Response for the last payment which was processed. This response is typically a one letter indicator, meaning the following:<br />
**M- CVV2/CVC2 Match - Indicates that the card is authentic. Complete the transaction if the authorization request was approved.<br />
**N- CVV2 / CVC2 No Match – May indicate a problem with the card. Contact the cardholder to verify the CVV2 code before completing the transaction, even if the authorization request was approved.<br />
**P- Not Processed - Indicates that the expiration date was not provided with the request, or that the card does not have a valid CVV2 code. If the expiration date was not included with the request, resubmit the request with the expiration date.<br />
**S- Merchant Has Indicated that CVV2 / CVC2 is not present on card - May indicate a problem with the card. Contact the cardholder to verify the CVV2 code before completing the transaction.<br />
**U- Issuer is not certified and/or has not provided visa encryption keys<br />
* '''CCLastChargeResult''' - returns the gateway's result code for the last operation.<br />
* '''CCLastPaymentAuthCode''' - returns the gateway's approval code for the last payment which was processed with CCProcessPayment. <br />
* '''CCLastPaymentTransactionID'''- returns the gateway's transaction ID for the last payment which was processed with CCProcessPayment.<br />
* '''CCLastRawResponse'''- returns the gateway's raw text response for the most recent transaction.<br />
* '''CCValidateCardNumber''' (''cardNumber'') determines if a card number is valid. Does not indicate the validity of the card itself, only its number. Returns either a 1 for valid card, or 0 for invalid cards.<br />
* '''CCLastError''' - returns the text of the last error triggered by a plugin function. <br />
* '''CCLicenseInfo''' - returns information about the license used. <br />
* '''CCVersion''' - returns the version of the credit card plugin which is installed.</div>Sarahhttp://docs.360works.com/index.php/Template:Plugin_BasicsTemplate:Plugin Basics2013-11-07T21:01:36Z<p>Sarah: /* Demo mode and registering the plug-in */</p>
<hr />
<div>====Requirements====<br />
<br />
FileMaker 7 or higher, Java Virtual Machine (JVM) 1.5 or higher, Windows or Mac OS X 10.4. Rosetta on Intel Macs not supported.<br />
<br />
====Installation====<br />
<br />
To install the plug-in, copy the plug-in to the correct directory:<br />
<br />
''FileMaker Pro'': FileMaker / Extensions<br /><br />
''Web Publishing Engine'': FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins *<br /> <br />
''Custom Web Publishing'': FileMaker Server/Web Publishing/publishing-engine/cwpc/Plugins *<br /><br />
''Mac FileMaker Server Scheduled Scripts'': /Library/FileMaker Server/Database Server/Extensions *<br /><br />
''Windows FileMaker Server Scheduled Scripts'': C:\Program Files\FileMaker\FileMaker Server\Database Server\Extensions *<br /><br />
<nowiki>* (Requires Enterprise license)</nowiki><br />
<br />
Create the "Plugins" folder if it doesn't exits. Make sure to restart FileMaker Pro / Server / WPE. Enable the plug-in in FileMaker Server Admin console for scheduled scripts on the server. For users running 64-bit versions of Windows and FileMaker Server 12.02 and later, use the 64 bit version of the plug-in in the custom web publishing location ''only.'' The 64 bit plug-in is marked with .fmx64<br />
<br />
====Uninstalling the plug-in====<br />
<br />
Uninstall the plug-in by quitting FileMaker Pro or stopping FileMaker Server and removing the plug-in file from your Extensions directory.<br />
<br />
====Demo mode and registering the plug-in====<br />
<br />
Plug-ins will run in a fully featured demo mode until they are registered. While running in demo mode, the product will run for 2 hours every time you launch FileMaker / FileMaker Server / FileMaker Web Publishing Engine until restarted. Enter the license information in FileMaker Preferences, or by using a script and calling <code>CCRegister</code>.<br />
<br />
Set Variable [ $register Value:<br />
CCRegister ( licenseKey, registeredTo)<br />
<br />
'''Returns''': a 1 on success or a 0 on failure.<br />
<br />
====Error Handling/Reporting====<br />
<br />
When something unexpected happens, the plug-in will pop up a dialog showing what the error message is. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call <code>CCSetErrorCapture</code> with a parameter of true. That will suppress the error dialog from appearing to the user.<br />
<br />
Whether or not you suppress the error dialogs, a plugin function will return the word <code>ERROR</code> if something goes wrong. It's a good idea to put your plugin functions in an 'If' statement so that you don't execute a bunch of script steps after something has gone wrong. If you'd like for your script to get the error message, you can get that by calling the <code>CCLastErrror</code> function. For example:<br />
<br />
<pre><br />
Set Variable [ $result = MyPluginFunction("x" ; "y" ; "z") ]<br />
If [ $result = "ERROR" ]<br />
Show Custom Dialog [ "An error occurred: " & CCLastError ]<br />
End If<br />
</pre><br />
<br />
If a plug-in is not installed correctly, calls to a plug-in function will return "?"<br />
<br />
'''More Information'''<br />
<br />
For more information on how to correctly install and work with plug-ins, check out the [[Plugins 101]] documentation.</div>Sarahhttp://docs.360works.com/index.php/VirtualMerchantVirtualMerchant2013-11-07T20:59:02Z<p>Sarah: /* VirtualMerchant */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
== VirtualMerchant==<br />
<br />
VirtualMerchant can process a variety of transactions, including voids, refunds, card not present and swiped cards, as well as recurring charges.. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [https://www.myvirtualmerchant.com/VirtualMerchant/ Virtual Merchant Gateway], and use your '''merchant ID''' and the '''PIN''' as the first two parameters for every plug-in function call that performs a transaction. You'll also need the user name, provided by Virtual Merchant, provided as an additional but required parameter. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of merchant ID and PIN. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantID;<br />
pin;<br />
"user=joe" ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("VirtualMerchant")]<br />
<br />
'''Returns''': 1 on success, "ERROR" on failure.<br />
<br />
If running card present charges, you should also set cardPresent to true when setting the gateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("VirtualMerchant"; "cardPresent=true")<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
Once you properly configure your merchant account, you can quickly and easily process payment transactions.<br />
<br />
You must provide the following information for a credit card payment transaction:<br />
*merchant account name (this might also be known as a store id)<br />
*transaction key (this might also be known as a password or token)<br />
*dollar amount<br />
*credit card number<br />
*credit card expiration date<br />
*VirtualMerchant user<br />
<br />
The CCProcessPayment function will process a transaction and return a transaction ID. This function returns a transaction ID if the transaction is successful or the word ERROR if the transaction fails. For detailed information about the most recent transaction failure, call the CCLastError function before calling any other transaction-processing function.<br />
<br />
In your script, you would then have a second line after setting the gateway.<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessPayment(<br />
merchantID, <br />
PIN;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"user=demoaccount")<br />
</pre><br />
<br />
'''Returns''': the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem <br />
<br />
'''Note''': It is important to store the resulting transaction ID because you may need it later to void the transaction, issue a refund or capture a previously authorized transaction.<br />
<br />
Since the user is a required piece of information for VirtualMerchant, but it's not part of the signature, add the information with the "key=value" syntax.<br />
<br />
You may submit optional parameters to most of Plastic's payment-transaction processing functions. These parameters will be submitted to the payment gateway along with the basic transaction information. Although they are not usually required to process an order, these parameters can be useful for tasks such as address verification or linking a transaction to a customer id or an invoice number. To supply additional parameters to a function call, add them to the end of the parameter list after the last required parameter, using a "key=value" syntax.<br />
<br />
<pre>Set Variable $result Value:<br />
CCProcessPayment(<br />
merchantID, <br />
PIN;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"user=demoaccount";<br />
"chargeDescription=" & Payment::description;<br />
"verificationCode=" & $securityCode)</pre><br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|verificationCode <br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|-<br />
|invoiceNumber<br />
|an arbitrary invoice number for your records<br />
|-<br />
|customerId<br />
|an arbitrary customer ID for your records<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|zip<br />
|the billing address zip<br />
|}<br />
</center><br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
Set Variable [$result; Value:CCProcessPayment(merchantID;PIN;chargeAmount;"";"";<br />
"user=demoaccount";<br />
"track1=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
<br />
Pass in either track1 or track2.<br />
=== Voiding Transactions ===<br />
<br />
<pre>Set Variable [$result; Value: <br />
CCVoidPayment ( <br />
merchantID ; <br />
PIN ; <br />
previousTransactionID;<br />
"user=demoaccount")]</pre><br />
<br />
Voids a previously processed payment. The parameters are similar to the CCProcessPayment function, except dollarAmount is replaced with the addition of the previousTransactionID parameter. The previousTransactionID should be the transaction ID of the transaction you wish to void. This value is returned by the CCProcessPayment function. Alternately, you can use the CCLastPaymentTransactionID function to get the transactionID of the last processed payment.<br />
<br />
Note that CCVoidPayment will only work on orders that have not settled yet, which means that it will generally only work on payments made that same day. To void settled orders, use CCRefund instead.<br />
<br />
'''Returns''': the transaction ID from the payment gateway service if the order is successful, or "ERROR" if there was a problem <br />
<br />
See also: CCLastPaymentTransactionIDReturns: the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem (use CCLastError for more detailed information about the nature of the error)<br />
<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
To credit a transaction, you need the transaction ID returned by CCProcessPayment. Pass this (along with other payment info) to the CCRefund function. This is similar to the void process, except it accepts a dollar amount and the credit card number (or the last four digits of the credit card number) used to process the original transaction.<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCRefund(<br />
merchantID;<br />
PIN; <br />
transactionID;<br />
cardNumber;<br />
dollarAmount;<br />
"user=demoaccount")]<br />
</pre><br />
<br />
'''Returns''': the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem <br />
<br />
If you do not pass a dollar amount, it will refund the whole amount of the transaction. <br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction. It will be a little different based on whether it was a swiped or a typed card:<br />
<br />
{|<br />
|-<br />
|''Credit Not Present Unlinked Refund''<br />
|''Card Present Unlinked Refund''<br />
|-<br />
| <pre>Set Variable [$result Value:<br />
CCRefund(<br />
merchantID,<br />
PIN;<br />
"";<br />
cardNumber;<br />
chargeAmount;<br />
"user=demoaccount";<br />
"expirationDate=12/13")]<br />
<br />
</pre><br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
merchantID,<br />
PIN;<br />
"";<br />
"";<br />
chargeAmount;<br />
"user=demoaccount";<br />
"track1=";<br />
"track2=")<br />
</pre><br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
With subscriptions, payments can automatically be debited to a credit card or a bank account on a time period you specify. To create a credit card subscription, use '''CCCreateSubscription'''. After a subscription has been created, it can be modified with '''CCModifySubscription'''. Items in italics are optional.<br />
<br />
Valid pay periods include: daily, weekly, biweekly, semi-monthly, monthly, bi-monthly, quarterly, semester, semi-annually, and annually.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCModifySubscription</big><br />
|-<br />
|merchantID||merchantID<br />
|-<br />
|PIN||PIN<br />
|-<br />
|dollarAmount||previousSubscriptionId<br />
|-<br />
|cardNumber||''dollarAmount''<br />
|-<br />
|expirationDate||''cardNumber''<br />
|-<br />
|";||''expirationDate''<br />
|-<br />
|"";||"";<br />
|-<br />
|startDate||"";<br />
|-<br />
|payPeriod||''startDate''<br />
|-<br />
|"";||''payPeriod''<br />
|-<br />
|"user="||"";<br />
|-<br />
| || "user="<br />
|}<br />
<br />
'''Returns''': 1 on success, "ERROR" on failure.<br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying subscriptions:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
|-<br />
|verificationCode||invoiceNumber<br />
|-<br />
|customerId||address<br />
|-<br />
|zip<br />
|}<br />
</center><br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|merchantID<br />
|-<br />
|PIN<br />
|-<br />
|previousSubscriptionId<br />
|-<br />
|"user="<br />
|}<br />
<br />
'''Returns''': 1 on success, "ERROR" on failure.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/USA_ePAYUSA ePAY2013-11-07T20:58:46Z<p>Sarah: /* USA ePay */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==USA ePay==<br />
<br />
USA ePay can process a wide variety of transactions, including eCheck / ACH payments, profile-based payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [http://www.usaepay.com/resellerlist USA ePay Gateway], and use your '''source key''' and the '''PIN''' as the first two parameters for every plug-in function call that performs a transaction. You can log into your account at USA ePay and generate the PIN there. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of source key and PIN. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
sourceKey;<br />
pin; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("USA ePay")]<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
If running card present charges, you should also set cardPresent to true when setting the gateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("USA ePay"; "cardPresent=true")<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
{{Template:Processing Payments|merchantId|pin|}}<br />
<br />
{{Template:USA Optional Parameters}}<br />
<br />
=== Processing ACH payments ===<br />
<br />
Plastic 2 now supports payments via direct bank transfers and eChecks, via ACH payments. To take a payment via eCheck, use the '''CCProcessPaymentACH''' function after calling the gateway. <br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPaymentACH ( <br />
sourceKey; <br />
pin; <br />
dollarAmount;<br />
accountNumber; <br />
routingNumber;<br />
""; <br />
accountType; <br />
accountHolderFirstName; <br />
accountHolderLastName;<br />
checkNumber;<br />
"achType=ARC";<br />
"driversLicenseNumber=2345431";<br />
"driversLicenseState=GA")]</pre><br />
<br />
You must pass in the ACH Type and driver's license information. Do so by adding the extra parameters as key=value pairs. The blank placeholder is marked with ""; - normally you would use this parameter for a bank name, but that is not supported in USA ePay transactions. <br />
<br />
If taking a Account Receivable Transaction (ARC) or Back Office Conversion (BOC) payment, you must also pass in a check number. If not, simply type ""; where that checkNumber field would be.<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|invoiceNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|poNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|currency<br />
|the currency used in the transaction<br />
|-<br />
|orderId <br />
|an arbitrary order number for your records<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|companyName<br />
|the billing company name<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|address2<br />
|the second line of the billing address<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|-<br />
|shipFirstName <br />
|the shipping recipient's first name<br />
|-<br />
|shipLastName <br />
|the shipping recipient's last name<br />
|-<br />
|shipEmail <br />
|the shipping recipient's email<br />
|-<br />
|shipPhone <br />
|the shipping recipient's phone<br />
|-<br />
|shipFax <br />
|the shipping recipient's fax number<br />
|-<br />
|shipCompanyName<br />
|the shipping company name<br />
|-<br />
|shipAddress <br />
|the shipping street address<br />
|-<br />
|shipAddress2 <br />
|the shipping address second line<br />
|-<br />
|shipCity <br />
|the shipping address city<br />
|-<br />
|shipState <br />
|the shipping address state<br />
|-<br />
|shipZip <br />
|the shipping address zip<br />
|-<br />
|shipCountry<br />
|the shipping address country<br />
|}<br />
</center><br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|sourceKey|pin}}<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessAuthorizedPayment(<br />
sourceKey, <br />
pin;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre><br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
sourceKey;<br />
pin;<br />
chargeAmount;<br />
"";<br />
"";<br />
"track1=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
</pre><br />
<br />
Pass in either track1 or track2.<br />
<br />
=== Partial Transactions === <br />
<br />
When using CCProcessPayment, specifying the additional parameter "authMode=AUTH_ONLY" will perform an authorization as opposed to a sale transaction. Specifying the "isPartialAuthorization=true" parameter will tell the gateway to allow for partial authorizations of pre-paid credit cards, gift cards and debit cards. <br />
<br />
After specifying a partial authorization, you can request the remaining balance and the requested amount by using CCPartialGetRemainingBalance and CCPartialGetRequestedAmount. Both return the dollar amounts, and do not require any additional parameters.<br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|sourceKey|pin}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|sourceKey|pin}}<br />
<br />
If you do not pass a dollar amount, it will refund the whole amount of the transaction. <br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction. It will be a little different based on whether the refund is from an ACH or credit card:<br />
<br />
{|<br />
|-<br />
|''Credit Card Unlinked Refund''<br />
|''ACH Unlinked Refund''<br />
|-<br />
| <pre>Set Variable [$result Value:<br />
CCRefund(<br />
sourceKey,<br />
pin;<br />
"";<br />
cardNumber;<br />
chargeAmount;<br />
"expirationDate=12/13")]<br />
<br />
</pre><br />
|| <pre>Set Variable [$result Value:<br />
CCRefund(<br />
sourceKey,<br />
pin;<br />
"";<br />
accountNumber;<br />
chargeAmount;<br />
"routingNumber=";<br />
"accountType=";<br />
"achType=";<br />
"driversLicenseNumber=";<br />
"driversLicenseState=";<br />
"checkNumber=")]<br />
</pre><br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
USA ePay supports all five subscription functions. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. <br />
<br />
Valid pay periods include daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, and annually. The number of installments specify how many transactions to run. A six month subscription would specify a payPeriod of monthly, and 6 installments.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use '''CCCreateSubscriptionACH.''' Italicized items are optional.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||accountHolderFirstName<br />
|-<br />
|payPeriod||accountHolderLastName<br />
|-<br />
|"";||"";<br />
|-<br />
|||numberOfInstallments<br />
|-<br />
| || startDate<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
'''Returns''': the subscription ID on success, "ERROR" on failure. <br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''. The optional parameters can be set to "" if you do not need to modify them. The last two, marked with ""; are payPeriod and frequency, which cannot be modified. <br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big>|| <big>CCModifySubscriptionACH</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|''dollarAmount''||''dollarAmount''<br />
|-<br />
|''cardNumber''||''accountNumber''<br />
|-<br />
|''expirationDate''||''abaRoutingNumber''<br />
|-<br />
|"";||"";<br />
|-<br />
|''numberOfInstallments''||''accountType''<br />
|-<br />
|''startDate''||''accountHolderFirstName''<br />
|-<br />
|payPeriod||''accountHolderLastName''<br />
|-<br />
|"";||"";<br />
|-<br />
|||''numberOfInstallments''<br />
|-<br />
| || ''startDate''<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying credit card subscriptions:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|maxFailures<br />
|the maximum amount of times that the charge should try<br />
|-<br />
|poNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|currency <br />
|the charge currency<br />
|-<br />
|orderId<br />
|an arbitrary order number for your records<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|companyName<br />
|the card holder's company name<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|address2<br />
|the billing address second line<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|}<br />
</center><br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying ACH subscriptions:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|achType<br />
|the classification of ACH transaction type<br />
|-<br />
|driversLicenseNumber<br />
|the account holder's driver's license number<br />
|-<br />
|driversLicenseState<br />
|the account holder's driver's license state<br />
|-<br />
|maxFailures<br />
|the maximum amount of times that the charge should try<br />
|-<br />
|poNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|currency <br />
|the charge currency<br />
|-<br />
|orderId<br />
|an arbitrary order number for your records<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|companyName<br />
|the card holder's company name<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|address2<br />
|the billing address second line<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|}<br />
</center><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|sourceKey<br />
|-<br />
|pin<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
== Payment Profiles ==<br />
<br />
{{Template:Customer profiles|sourceKey|pin}}<br />
<br />
{{Template:Profiles}}<br />
<br />
You don't necessarily need to pass in a customer ID for creating or updating a customer profile. <br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying customers:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
|-<br />
|profileDescription<br />
|-<br />
|firstName<br />
|-<br />
|lastName<br />
|-<br />
|email<br />
|-<br />
|phone<br />
|-<br />
|fax<br />
|-<br />
|companyName<br />
|-<br />
|address<br />
|-<br />
|address2<br />
|-<br />
|city<br />
|-<br />
|state<br />
|-<br />
|zip<br />
|-<br />
|country<br />
|}<br />
</center><br />
<br />
=== Creating Payment Profiles===<br />
<br />
Payment profiles allow you to save payment information straight to the gateway for future use. To create a payment profile, call either '''CCProfileCreatePayment''' or '''CCProfileCreatePaymentACH''', depending on whether the payment profile is a credit card or ACH. Credit cards are created with '''CCProfileCreatePayment''' and updated with '''CCProfileUpdatePayment'''. Italicized items are optional, and can accept ""; if not needed.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePayment</big><br />
| <big>CCProfileUpdatePayment</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|cardNumber||paymentProfileId<br />
|-<br />
|expirationDate||''cardNumber''<br />
|-<br />
|||''expirationDate''<br />
|}<br />
<br />
'''Returns''': Creating a payment will return the ID of the profile created, "ERROR" on failure. Updating will return 1 on success, "ERROR" on failure.<br />
<br />
Optional parameters: profileDescription, verificationCode.<br />
<br />
After creation, payments can be retrieved with '''CCProfileGetPayment''' Payments can be deleted with '''CCProfileDeletePayment'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileGetPayment</big><br />
| <big>CCProfileDeletePayment</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|paymentProfileId||paymentProfileId<br />
|}<br />
<br />
'''Returns''': Getting a payment will return the ID of the profile requested, "ERROR" on failure. Deletions will return 1 on success, "ERROR" on failure.<br />
<br />
ACH payments are added and updated in much the same way as a credit card. Italicized items are optional, and can accept ""; if not needed. ACH payments can use the same CCProfileGetPayment, CCProfileValidatePayment, and CCProfileDeletePayment as above.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePaymentACH</big>||<big>CCProfileUpdatePaymentACH</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|accountNumber||paymentProfileId<br />
|-<br />
|routingNumber||''accountNumber''<br />
|-<br />
|"";||''routingNumber''<br />
|-<br />
|accountType||"";<br />
|-<br />
|"";||''accountType''<br />
|-<br />
|"";||"";<br />
|-<br />
|||"";<br />
|}<br />
<br />
'''Returns''': Creating a payment will return the ID of the profile created, "ERROR" on failure. Updating will return 1 on success, "ERROR" on failure.<br />
<br />
Optional parameters: achType, driversLicenseNumber, driversLicenseState.<br />
<br />
=== Running Charges Against Profiles ===<br />
<br />
You can process a payment and refund transactions using the saved payment data. Please note you'll need to mark whether the original payment method was an ACH or credit card using the key=value pair.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
| <big> CCProfileRefund </big><br />
|-<br />
|'''sourceKey'''||'''sourceKey'''<br />
|-<br />
|'''pin'''||'''pin'''<br />
|-<br />
|'''customerProfileId'''||'''customerProfileId'''<br />
|-<br />
|'''paymentProfileId'''||'''paymentProfileId'''<br />
|-<br />
|'''dollarAmount'''||'''previousTransactionId'''<br />
|-<br />
|"methodOfPayment=CC"||'''amountToCredit'''<br />
|-<br />
|||"";<br />
|-<br />
|||"methodOfPayment=ACH"<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters for CCProfileProcessPayment:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
!Parameters<br />
|-<br />
|verificationCode<br />
|invoiceNumber<br />
|-<br />
|poNumber<br />
|chargeDescription<br />
|-<br />
|customerId<br />
|currency<br />
|-<br />
|orderId<br />
|}<br />
<br />
</center><br />
<br />
'''Returns''': Payments return a transaction ID from the payment gateway service if the transaction is successful, or "ERROR" if there was a problem. Refunds will return 1 on success, or "ERROR" if there was a problem.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/TransFirstTransFirst2013-11-07T20:58:27Z<p>Sarah: /* TransFirst */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==TransFirst==<br />
<br />
TransFirst can process a wide variety of transactions, including eCheck / ACH payments, profile-based payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [http://www.transfirst.com/merchant-accounts TransFirst Gateway], and use your '''merchant ID''' and the '''hosted key''' as the first two parameters for every plug-in function call that performs a transaction. You'll receive these from TransFirst once you obtain a merchant account. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of merchant ID and hosted key. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantId; <br />
hostedKey; ; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("TransFirst")]<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
If running card present charges, you should also set cardPresent to true when setting the gateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("TransFirst"; "cardPresent=true")==Processing Payments==<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
{{Template:Processing Payments|merchantId|hostedKey}}<br />
<br />
{{Template:TransFirst Optional Parameters}}<br />
<br />
=== Processing ACH Payments ===<br />
<br />
Plastic 2 now supports payments via direct bank transfers and eChecks, via ACH payments. To take a payment via <br />
eCheck, use the CCProcessPaymentACH function after calling the gateway.<br />
<br />
<pre><br />
Set Variable [$result; Value:<br />
CCProcessPaymentACH ( <br />
merchantId; <br />
hostedKey; <br />
dollarAmount;<br />
accountNumber; <br />
routingNumber;<br />
""; <br />
accountType; <br />
accountHolderFirstName; <br />
accountHolderLastName;<br />
"";<br />
"checkType=" )]</pre><br />
<br />
Notice the blanks-- normally you should pass in a bank name and a check number in those positions, but TransFirst does not require that information. It does, however, require a check type, so use the key=value syntax to pass in that required parameter. <br />
<br />
{{Template:TransFirst Optional Parameters}}<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
merchantId;<br />
hostedKey;<br />
chargeAmount;<br />
"";<br />
"";<br />
"swipe=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
</pre><br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|merchantId|hostedKey}}<br />
<br />
With TransFirst, you should also pass in the method of payment used: ACH or CC with "methodOfPayment="<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|merchantId|hostedKey}}<br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with TransFirst, pass in the blank transaction ID. It will be a little different based on whether it was a ACH or credit card:<br />
<br />
{|<br />
|-<br />
|''Credit Card Unlinked Refund''<br />
|''ACH Unlinked Refund''<br />
|-<br />
| <pre>Set Variable $result Value:<br />
CCRefund(<br />
merchantId,<br />
hostedKey;<br />
"";<br />
cardNumber;<br />
chargeAmount;<br />
"expirationDate=12/13")<br />
<br />
</pre><br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
merchantId,<br />
hostedKey;<br />
"";<br />
accountNumber;<br />
chargeAmount;<br />
"routingNumber="<br />
"checkType=")<br />
</pre><br />
|}<br />
<br />
<br />
CCRefund also allows you to submit an optional orderId. With a credit card refund, you can also pass in the verificationCode, poNumber, chargeDescription, firstName, lastName, address, and zip.<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
TransFirst supports all every function but deletions. To cancel a subscription, modify its properties instead. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. <br />
<br />
Valid pay periods include monthly, quarterly, yearly, weekly, bi-weekly, every4weeks, and every8weeks. The number of installments specify how many transactions to run. A six month subscription would specify a payPeriod of monthly, and 6 installments.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use '''CCCreateSubscriptionACH.''' Italicized items are optional.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|merchantId||merchantId<br />
|-<br />
|hostedKey||hostedKey<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||accountHolderFirstName<br />
|-<br />
|payPeriod||accountHolderLastName<br />
|-<br />
|"";||"";<br />
|-<br />
|||numberOfInstallments<br />
|-<br />
| || startDate<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
'''Returns''': the ID of the subscription created, "ERROR" on failure. <br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''. The optional parameters can be set to "" if you do not need to modify them. The last two, marked with ""; are payPeriod and frequency, which cannot be modified. <br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big>|| <big>CCModifySubscriptionACH</big><br />
|-<br />
|merchantId||merchantId<br />
|-<br />
|hostedKey||hostedKey<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|''dollarAmount''||''dollarAmount''<br />
|-<br />
|''cardNumber''||''accountNumber''<br />
|-<br />
|''expirationDate''||''abaRoutingNumber''<br />
|-<br />
|''subscriptionName''||''bankName''<br />
|-<br />
|''numberOfInstallments''||''accountType''<br />
|-<br />
|''startDate''||''accountHolderFirstName''<br />
|-<br />
|payPeriod||''accountHolderLastName''<br />
|-<br />
|"";||"";<br />
|-<br />
|||''numberOfInstallments''<br />
|-<br />
| || ''startDate''<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying subscriptions:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
|-<br />
|firstName ||lastName<br />
|-<br />
|address ||zip<br />
|}<br />
</center><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
==Payment Profiles==<br />
<br />
=== Creating Payment Profiles===<br />
<br />
Payment profiles allow you to save payment information straight to the gateway for future use. To create a payment profile, call either '''CCProfileCreatePayment''' or '''CCProfileCreatePaymentACH''', depending on whether the payment profile is a credit card or ACH. Credit cards are created with '''CCProfileCreatePayment''' and updated with '''CCProfileUpdatePayment'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePayment</big><br />
| <big>CCProfileUpdatePayment</big><br />
|-<br />
|merchantId<br />
|merchantId<br />
|-<br />
|hostedKey<br />
|hostedKey<br />
|-<br />
|customerProfileId<br />
|customerProfileId<br />
|-<br />
|cardNumber<br />
|paymentProfileId<br />
|-<br />
|expirationDate<br />
|''cardNumber''<br />
|-<br />
|<br />
|''expirationDate''<br />
|}<br />
<br />
'''Returns''': Creating a payment will return the ID of the profile created, "ERROR" on failure. Updating will return 1 on success, "ERROR" on failure.<br />
<br />
After creation, payments can be retrieved with '''CCProfileGetPayment'''. Payments can be deleted with '''CCProfileDeletePayment'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileGetPayment</big><br />
| <big>CCProfileDeletePayment</big><br />
|-<br />
|merchantId<br />
|merchantId<br />
|-<br />
|hostedKey<br />
|hostedKey<br />
<br />
|-<br />
|customerProfileId<br />
|customerProfileId<br />
<br />
|-<br />
|paymentProfileId<br />
|paymentProfileId<br />
|}<br />
<br />
'''Returns''': Getting a payment will return the ID of the profile requested, "ERROR" on failure. Deletions will return 1 on success, "ERROR" on failure.<br />
<br />
Card number and expiration dates are not required when updating the payment.<br />
<br />
{{Template:Profiles}}<br />
<br />
ACH payments are added and updated in much the same way as a credit card. Italicized items are optional, and can accept ""; if not needed. ACH payments can use the same CCProfileGetPayment and CCProfileDeletePayment as above.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePaymentACH</big>||<big>CCProfileUpdatePaymentACH</big><br />
|-<br />
|merchantId||merchantId<br />
|-<br />
|hostedKey||hostedKey<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|accountNumber||paymentProfileId<br />
|-<br />
|routingNumber||''accountNumber''<br />
|-<br />
|"";||''routingNumber''<br />
|-<br />
|''accountType''||''bankName''<br />
|-<br />
|''accountHolderFirstName''||''accountType''<br />
|-<br />
|''accountHolderLastName''||''accountHolderFirstName''<br />
|-<br />
|||''accountHolderLastName''<br />
|}<br />
<br />
For TransFirst, creating and updating payments accept the following:<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
!Parameters<br />
|-<br />
|poNumber<br />
|chargeDescription<br />
|-<br />
|firstName<br />
|lastName<br />
|-<br />
|companyName<br />
|address<br />
|-<br />
|address<br />
|zip<br />
|-<br />
|orderId<br />
|}<br />
</center><br />
<br />
'''Returns''': Creating a payment will return the ID of the profile created, "ERROR" on failure. Updating will return 1 on success, "ERROR" on failure.<br />
<br />
=== Running Charges Against Profiles ===<br />
<br />
To process a payment after it has been saved, use CCProfileProcessPayment.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
|-<br />
|'''merchantId'''<br />
|-<br />
|'''hostedKey'''<br />
|-<br />
|'''customerProfileId'''<br />
|-<br />
|'''paymentProfileId'''<br />
|-<br />
|'''dollarAmount'''<br />
|-<br />
|"methodOfPayment="<br />
|-<br />
|"customerId="<br />
|-<br />
|"verificationCode="<br />
|}<br />
<br />
'''Returns''': a transaction ID from the payment gateway service if the transaction is successful, or "ERROR" if there was a problem.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/RealExRealEx2013-11-07T20:58:14Z<p>Sarah: /* RealEx */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==RealEx==<br />
<br />
RealEx supports running charges, authorizations and captures, and payment profiles. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [http://www.realexpayments.com/home RealEx Gateway], and use your '''merchant ID''' and the '''account name''' as the first two parameters for every plug-in function call that performs a transaction. You'll also need the shared secret, provided by RealEx, provided as an additional but required parameter. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of merchant ID and account name. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantID;<br />
accountName;<br />
"sharedSecret=shh" ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("RealEx")<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
If running card present charges, you should also set cardPresent to true when setting the gateway.<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("RealEx"; "cardPresent=true")]</pre><br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
Once you properly configure your merchant account, you can quickly and easily process payment transactions.<br />
You must provide the following information for a credit card payment transaction:<br />
<br />
*merchant ID<br />
*account name<br />
*dollar amount<br />
*credit card number<br />
*credit card expiration date<br />
*shared secret<br />
*order ID<br />
<br />
The CCProcessPayment function will process a transaction and return a transaction ID. This function returns a transaction ID if the transaction is successful or the word ERROR if the transaction fails. For detailed information about the most recent transaction failure, call the CCLastError function before calling any other transaction-processing function.<br />
<br />
In your script, you would then have a second line after setting the gateway.<br />
<pre>Set Variable [$result Value: <br />
CCProcessPayment(<br />
merchantId;<br />
accountName;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"sharedSecret=";<br />
"orderId=")]<br />
</pre> <br />
<br />
'''Returns''': a verification code from the payment gateway service if the order is successful, or "ERROR" if there was a problem <br />
<br />
'''Note''': It is important to store the resulting transaction ID because you may need it later to void the transaction, issue a refund or capture a previously authorized transaction.<br />
<br />
You may submit optional parameters to most of Plastic's payment-transaction processing functions. These parameters will be submitted to the payment gateway along with the basic transaction information. Although they are not usually required to process an order, these parameters can be useful for tasks such as address verification or linking a transaction to a customer id or an invoice number. To supply additional parameters to a function call, add them to the end of the parameter list after the last required parameter, using a "key=value" syntax.<br />
<br />
Set Variable $result Value:<br />
CCProcessPayment(<br />
merchantId,<br />
accountName;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"sharedSecret=";<br />
"orderId=";<br />
"chargeDescription=" & Payment::description;<br />
"verificationCode=" & $securityCode)<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|verificationCode <br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|-<br />
|shipAddress <br />
|the shipping street address<br />
|-<br />
|shipZip <br />
|the shipping address zip<br />
|-<br />
|shipCountry <br />
|the shipping address country<br />
|-<br />
|currency <br />
|the type of currency<br />
|-<br />
|card type <br />
|the type of card used<br />
|}<br />
</center><br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
Use '''CCProcessAuthorizedPayment'''. Normally, you would also pass in a dollarAmount as the final variable, but this is not required in RealEx. Instead, use ""; for the final parameter and add the sharedSecret and orderID.<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessAuthorizedPayment(<br />
merchantId, <br />
accountName;<br />
previousTransactionId;<br />
"";<br />
"sharedSecret=";<br />
"orderId=")<br />
</pre><br />
<br />
<br />
=== Voiding Transactions ===<br />
<br />
<pre><br />
Set Variable [$result; Value: <br />
CCVoidPayment ( <br />
merchantId ;<br />
accountName ; <br />
previousTransactionID;<br />
"sharedSecret=";<br />
"orderId=")]<br />
</pre> <br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
Voids a previously processed payment. The parameters are similar to the CCProcessPayment function, except dollarAmount is replaced with the addition of the previousTransactionID parameter. The previousTransactionID should be the transaction ID of the transaction you wish to void. This value is returned by the CCProcessPayment function. Alternately, you can use the CCLastPaymentTransactionID function to get the transactionID of the last processed payment.<br />
<br />
Note that CCVoidPayment will only work on orders that have not settled yet, which means that it will generally only work on payments made that same day. To void settled orders, use CCRefund instead.<br />
<br />
See also: CCLastPaymentTransactionID, which returns the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem (use CCLastError for more detailed information about the nature of the error).<br />
<br />
Optionally, you can also pass in a chargeDescription.<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
To credit a transaction, you need the transaction ID returned by CCProcessPayment. Pass this (along with other payment info and the refund password) to the CCRefund function. This is similar to the void process, except it accepts a dollar amount and the credit card number (or the last four digits of the credit card number) used to process the original transaction.<br />
<br />
<pre><br />
Set Variable [$result; Value:<br />
CCRefund( <br />
merchantId; <br />
accountName; <br />
transactionID; <br />
cardNumber; <br />
dollarAmount;<br />
"sharedSecret=";<br />
"refundPassword=";<br />
"orderId=" </pre><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
You can also pass in a chargeDescription and currency as optional parameters.<br />
<br />
== Payment Profiles ==<br />
<br />
=== Creating Customer Profiles===<br />
<br />
Profiles save payment and customer data straight to the gateway securely for future use. To create a customer profile, call '''CCProfileCreateCustomer'''. After creation, update the customer information with '''CCProfileUpdateCustomer'''. Create your own customer ID for use with RealEx and pass it to customerId with creation. After that, use that same ID in the customerProfileId on update.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreateCustomer</big>|| <big>CCProfileUpdateCustomer</big><br />
|-<br />
|merchantId||merchantId<br />
|-<br />
|accountName||accountName<br />
|-<br />
|customerId||"";<br />
|-<br />
|"sharedSecret="||customerProfileId<br />
|-<br />
|"orderId="||"sharedSecret="<br />
|-<br />
|||"orderId="<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
!Parameter<br />
|-<br />
|profileDescription||firstName<br />
|-<br />
|lastName||companyName<br />
|-<br />
|email || phone<br />
|-<br />
|fax || address<br />
|-<br />
|address2||city<br />
|-<br />
|zip||country<br />
|-<br />
|colspan="2"|countryCode - if you provide a country name, you must also add the ISO country code.<br />
|}<br />
</center><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
{{Template:Profiles}}<br />
<br />
=== Creating Payment Profiles===<br />
<br />
To create a payment, use '''CCProfileCreatePayment'''. You can also update the payment method with '''CCProfileUpdatePayment'''. Both also accept "cardType=" as an optional parameter.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePayment</big>|| <big>CCProfileUpdatePayment</big><br />
|-<br />
|merchantId||merchantId<br />
|-<br />
|accountName||accountName<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|cardNumber||paymentProfileId<br />
|-<br />
|expirationDate||''cardNumber''<br />
|-<br />
|"sharedSecret="||expirationDate<br />
|-<br />
|"orderId="||"sharedSecret="<br />
|-<br />
|"paymentProfileId="||"firstName="<br />
|-<br />
|"firstName="||"lastName="<br />
|-<br />
|"lastName="||<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
After creation, payments can be deleted with '''CCProfileDeletePayment'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileDeletePayment</big><br />
|-<br />
|merchantId<br />
|-<br />
|accountName<br />
|-<br />
|customerProfileId<br />
|-<br />
|paymentProfileId;<br />
|-<br />
|"sharedSecret="<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
=== Running Charges Against Profiles ===<br />
<br />
You can process a payment or refund a payment using this payment profile. Items in bold are required.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
| <big> CCProfileRefund </big><br />
|-<br />
|merchantId||merchantId<br />
|-<br />
|accountName||accountName<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|paymentProfileId||paymentProfileId<br />
|-<br />
|dollarAmount||previousTransactionId<br />
|-<br />
|sharedSecret="||amountToCredit<br />
|-<br />
|"orderId="||"";<br />
|-<br />
|||"sharedSecret="<br />
|-<br />
|||"orderId="<br />
|-<br />
|||"refundPassword="<br />
|}<br />
<br />
'''Returns''': a transaction ID from the payment gateway service if the transaction is successful, or "ERROR" if there was a problem<br />
<br />
CCProfileProcessPayment and CCProfileRefund accept the following parameters as well:<br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|verificationCode (only payment, not refunds)||currency<br />
|-<br />
|chargeDescription||customerId<br />
|-<br />
|address||zip<br />
|-<br />
|country||shipAddress<br />
|-<br />
|shipZip||shipCountry<br />
|}<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/Payflow_ProPayflow Pro2013-11-07T20:57:53Z<p>Sarah: /* PayPal Payflow Pro */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==PayPal Payflow Pro==<br />
<br />
Payflow Pro can process a wide variety of transactions, including eCheck / ACH payments, card present swipes, and more. Payflow Pro can also set up a subscription, which automatically charges a credit card or debits a bank account on a set basis. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [https://registration.paypal.com/welcomePage.do?producttype=C2&country=US&mode=try|PayPal PayFlow Pro Gateway], and use your '''merchant login''' and the '''password''' as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of merchant login and password. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
If you can log on to [http://manager.paypal.com manager.paypal.com] with your credentials, you'll be able to use the Plastic plug-in. If you received an account directly from PayPal, you can use "PayPal" as the partner at the log-in screen. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantLogin;<br />
password;<br />
...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. <br />
<br />
Set Variable [$gateway; Value:CCSetGateway("Payflow Pro")<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
If running card present charges, you should also set cardPresent to true when setting the gateway.<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("Payflow Pro"; "cardPresent=true")]</pre><br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
Before running any charges or transactions, first evaluate if you must set up the user and partner. User is required if you have set up an additional user (besides the default merchant log in ID) for your PayFlow Pro account and you wish to run a transaction as that user. Partner is required if your Payflow Pro account was purchased from a reseller. Pass the ID provided by the reseller who registered you for the Payflow Pro service. '''If you meet these conditions, pass these values in every time you use payment processing functions'''.<br />
<br />
"user=account1"<br />
"partner=1234190"<br />
<br />
{{Template:Processing Payments|merchantLogin|password}}<br />
{{Template:PayFlow Pro Optional Parameters}}<br />
<br />
=== Processing ACH Payments ===<br />
<br />
{{Template:Processing ACH payments|merchantLogin|password}}<br />
<br />
For Payflow Pro, bankName is not an accepted parameter. Therefore, you must pass a blank value instead:<br />
<br />
<pre>Set Variable [$result Value: <br />
CCProcessPaymentACH(<br />
merchantLogin, <br />
password;<br />
dollarAmount;<br />
accountNumber;<br />
routingNumber;<br />
"";<br />
accountType;<br />
accountHolderFirstName;<br />
accountHolderLastName;<br />
checkNumber;<br />
"achType=ARC")<br />
</pre><br />
<br />
If taking a Account Receivable Transaction (ARC), Back Office Conversion (BOC), or Point of Purchase (POP) payment, you must also pass in a check number. If not, simply type ""; where that checkNumber field would be. <br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|invoiceNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|poNumber <br />
|an arbitrary PO number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|companyName <br />
|the billing company name<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|-<br />
|shipAddress <br />
|the shipping street address<br />
|-<br />
|shipCity <br />
|the shipping address city<br />
|-<br />
|shipCountry <br />
|the shipping address country<br />
|-<br />
|shipFirstName <br />
|the shipping recipient's first name<br />
|-<br />
|shipLastName <br />
|the shipping recipient's last name<br />
|-<br />
|shipState <br />
|the shipping address state<br />
|-<br />
|shipZip <br />
|the shipping address zip<br />
|-<br />
|shipEmail<br />
|the shipping recipient's email<br />
|-<br />
|shipPhone<br />
|the shipping recipient's phone<br />
|-<br />
|shipFax<br />
|the shipping recipient's fax<br />
|}<br />
</center><br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|merchantLogin|password}}<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessAuthorizedPayment(<br />
merchantLogin, <br />
password;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre>CCProcessAuthorizedPayment accepts the same optional parameters as CCProcessPayment.<br />
<br />
<br />
<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
merchantLogin;<br />
password;<br />
chargeAmount;<br />
"";<br />
"";<br />
"track1=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
</pre><br />
<br />
=== Partial Transactions === <br />
<br />
When using CCProcessPayment, specifying the additional parameter "authMode=AUTH_ONLY" will perform an authorization as opposed to a sale transaction. Specifying the "isPartialAuthorization=true" parameter will tell the gateway to allow for partial authorizations of pre-paid credit cards, gift cards and debit cards. <br />
After specifying a partial authorization, you can request the remaining balance and the requested amount by using CCPartialGetRemainingBalance and CCPartialGetRequestedAmount. Both return the dollar amounts, and do not require any additional parameters. <br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|merchantLogin|password}}<br />
<br />
{{Template:PayFlow Pro Optional Parameters}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|merchantLogin|password}}<br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with PayFlow Pro, pass in the blank transaction ID. It will be a little different based on whether it was a swiped or a typed card:<br />
<br />
{|<br />
|-<br />
|''Card Not Present Unlinked Refund''<br />
|''Card Present Unlinked Refund''<br />
|-<br />
| <pre>Set Variable $result Value:<br />
CCRefund(<br />
merchantLogin,<br />
password;<br />
"";<br />
cardNumber;<br />
chargeAmount;<br />
"expirationDate=12/13")<br />
<br />
</pre><br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
merchantLogin,<br />
password;<br />
"";<br />
"";<br />
chargeAmount;<br />
"track1=";<br />
"track2=")<br />
</pre><br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
Payflow Pro supports all five subscription functions. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. In addition, you can specify a trialAmount, which will perform a charge for the amount prior to the start of the subscription as an optional parameter. A final optional parameter is available for subscriptions, called subscriptionMaxFailures.<br />
<br />
Valid pay periods include: week, biwk, smmo, frwk, mont, qter, smyr, and year. <br />
<br />
*WEEK: Weekly - Every week on the same day of the week as the first payment.<br />
*BIWK: Every Two Weeks - Every other week on the same day of the week as the first payment.<br />
*SMMO: Twice Every Month - The 1st and 15th of the month. Results in 24 payments per year. SMMO can start on 1st to 15th of the month, second payment 15 days later or on the last day of the month.<br />
* FRWK: Every Four Weeks - Every 28 days from the previous payment date beginning with the first payment date. Results in 13 payments per year.<br />
* MONT: Monthly - Every month on the same date as the first payment. Results in 12 payments per year.<br />
*QTER: Quarterly - Every three months on the same date as the first payment.<br />
*SMYR: Twice Every Year - Every six months on the same date as the first payment.<br />
*YEAR: Yearly - Every 12 months on the same date as the first payment.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use '''CCCreateSubscriptionACH.''' <br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|merchantLogin||merchantLogin<br />
|-<br />
|txKey||txKey<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|subscriptionName||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||accountHolderFirstName<br />
|-<br />
|payPeriod||accountHolderLastName<br />
|-<br />
|"";||subscriptionName<br />
|-<br />
|||numberOfInstallments<br />
|-<br />
| || startDate<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
''Returns'': The subscription ID on success, "ERROR" if there was a problem.<br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''. The optional parameters can be set to "" if you do not need to modify them. The last two, marked with ""; are payPeriod and frequency, which cannot be modified. <br />
<br />
The trialOccurrences parameter can only be updated if the trial period has not begun or is in progress.<br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big>|| <big>CCModifySubscriptionACH</big><br />
|-<br />
|merchantLogin||merchantLogin<br />
|-<br />
|txKey||txKey<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|''dollarAmount''||''dollarAmount''<br />
|-<br />
|''cardNumber''||''accountNumber''<br />
|-<br />
|''expirationDate''||''abaRoutingNumber''<br />
|-<br />
|''subscriptionName''||"";<br />
|-<br />
|''numberOfInstallments''||''accountType''<br />
|-<br />
|''startDate''||''accountHolderFirstName''<br />
|-<br />
|''payPeriod''||''accountHolderLastName''<br />
|-<br />
|"";||''subscriptionName''<br />
|-<br />
|||''numberOfInstallments''<br />
|-<br />
| || ''startDate''<br />
|-<br />
| ||''payPeriod''<br />
|-<br />
| || "";<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
{{Template:PayFlow Pro Optional Parameters}}<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|merchantLogin<br />
|-<br />
|password<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
== Payment Profiles ==<br />
<br />
Typically, you pass a payment profile ID to the gateway for a Payment Profile. With Payflow Pro, there are no IDs. You can, however, pass in the previous transaction ID and use that to run another charge without having to rekey payment data.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
|-<br />
|merchantLogin<br />
|-<br />
|password<br />
|-<br />
|"";<br />
|-<br />
|paymentProfileId (previous transaction ID)<br />
|-<br />
|dollarAmount<br />
|}<br />
<br />
{{Template:PayFlow Pro Optional Parameters}}<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
With Payflow Pro, CCLastAVS may be a two character response, as they concatenate the domestic and international AVS together.<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}<br />
<br />
==Troubleshooting==<br />
<br />
* Determine whether the IP address of the machine you are using to process transactions has been added to the list of Allowed IP Addresses in PayPal Manager.<br />
** If you log into PayPal Manager, click the Service Settings tab and click the Allowed IP Addresses link, you will see a screen that allows you enter IP addresses from which transactions may originate. If all of the fields on this screen are empty, then there are no IP address restrictions for the account.<br />
** Do not confuse the Allowed IP Addresses link under the Service Settings tab with a similar link under the Account Administration tab. The latter Allowed IP Addresses link will take you to a screen that allows you to restrict which IP addresses may log into PayPal Manager.<br />
* Determine whether a separate transaction password has been configured in PayPal Manager.<br />
** If you log into PayPal Manager and click the Account Administration tab, you will see a link called Change Password. If you click the link, you will see a screen that will indicate whether a separate password has been configured for processing Payflow Pro transactions.<br />
* "Invalid vendor account" error<br />
** Usually caused when the partner is something other than PayPal and has been omitted or entered incorrectly.</div>Sarahhttp://docs.360works.com/index.php/PayTracePayTrace2013-11-07T20:57:34Z<p>Sarah: /* PayTrace */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==PayTrace==<br />
<br />
The PayTrace gateway supports a wide variety of transactions, profile based payments, and subscription payments. For detailed examples of each of these transactions, check the demo file included with your download of Plastic 2. These scripts are ready for insertion into your own solution! <br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [http://www.paytrace.com/front.default.pay PayTrace Gateway], and use your '''username''' and the '''password''' as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of username and password. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
username;<br />
password; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value: CCSetGateway ("PayTrace")]<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
If running card present charges, you should also set cardPresent to true when setting the gateway.<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("PayTrace"; "cardPresent=true")]</pre><br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
{{Template:Processing Payments|userName|password}}<br />
<br />
{{Template:PayTrace Optional Parameters}}<br />
<br />
=== Processing ACH payments ===<br />
<br />
Plastic 2 now supports payments via direct bank transfers and eChecks, via ACH payments. To take a payment via <br />
eCheck, use the CCProcessPaymentACH function after calling the gateway.<br />
<br />
<pre><br />
Set Variable [$result; Value:<br />
CCProcessPaymentACH ( <br />
userName; <br />
password; <br />
dollarAmount;<br />
accountNumber; <br />
routingNumber;<br />
""; <br />
""; <br />
accountHolderFirstName; <br />
accountHolderLastName;<br />
"" )]</pre><br />
<br />
With PayTrace, a bank name, account type, and check number are not required, so leave them blank by passing "";<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|invoiceNumber<br />
|an arbitrary invoice number for your records<br />
|-<br />
|chargeDescription<br />
|brief description of the charges<br />
|-<br />
|customerId<br />
|an arbitrary customer ID for your records<br />
|-<br />
|firstName<br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName<br />
|Last (surname) of the credit card holder<br />
|-<br />
|email<br />
|the card holder's email address<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|fax<br />
|the card holder's fax number<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|address2<br />
|the billing address second line<br />
|-<br />
|city<br />
|the billing address city<br />
|-<br />
|state<br />
|the billing address state<br />
|-<br />
|zip<br />
|the billing address zip<br />
|-<br />
|country<br />
|billing address country<br />
|-<br />
|shipFirstName<br />
|the shipping recipient's first name<br />
|-<br />
|shipLastName<br />
|the shipping recipient's last name<br />
|-<br />
|shipAddress<br />
|the shipping street address<br />
|-<br />
|shipAddress2<br />
|the shipping street address second line<br />
|-<br />
|shipCity<br />
|the shipping address city<br />
|-<br />
|shipState<br />
|the shipping address state<br />
|-<br />
|shipZip<br />
|the shipping address zip<br />
|-<br />
|shipCountry<br />
|the shipping address country<br />
|}<br />
</center><br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|userName|password}}<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessAuthorizedPayment(<br />
userName, <br />
password;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre><br />
<br />
The dollarAmount is not required to process the authorized payment. <br />
<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
userName;<br />
password;<br />
chargeAmount;<br />
"";<br />
"";<br />
"swipe=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
</pre><br />
<br />
=== Partial Transactions === <br />
<br />
When using CCProcessPayment, specifying the additional parameter "authMode=AUTH_ONLY" will perform an authorization as opposed to a sale transaction. Specifying the "isPartialAuthorization=true" parameter will tell the gateway to allow for partial authorizations of pre-paid credit cards, gift cards and debit cards. <br />
<br />
After specifying a partial authorization, you can request the remaining balance and the requested amount by using CCPartialGetRemainingBalance and CCPartialGetRequestedAmount. Both return the dollar amounts, and do not require any additional parameters. <br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|userName|password}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|userName|password}}<br />
<br />
Dollar amount is NOT a required value, and leaving it blank will simply refund the whole transaction.<br />
<br />
To refund an ACH payment, pass in the account number in the card number slot. It also requires adding routingNumber and methodOfPayment=ACH as parameters:<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCRefund(<br />
userName;<br />
password;<br />
previousTransactionId;<br />
accountNumber; <br />
amountToCredit; //Optional<br />
"routingNumber=";<br />
"methodOfPayment=ACH")]<br />
</pre><br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with PayTrace, pass in the blank transaction ID. It will be a little different based on whether it was a swiped or a typed card, or if it was an ACH:<br />
<br />
{|<br />
|-<br />
|''Card Not Present Unlinked Refund''<br />
|''Card Present Unlinked Refund''<br />
|''ACH Unlinked Refund''<br />
|-<br />
| <pre>Set Variable $result Value:<br />
CCRefund(<br />
userName,<br />
password;<br />
"";<br />
cardNumber;<br />
amountToCredit;<br />
"expirationDate=12/13")<br />
<br />
</pre><br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
userName,<br />
password;<br />
"";<br />
"";<br />
amountToCredit;<br />
"swipe=")<br />
<br />
</pre><br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
userName,<br />
password;<br />
"";<br />
accountNumber;<br />
amountToCredit;<br />
"routingNumber=";<br />
"methodOfPayment=ACH")<br />
</pre><br />
|}<br />
<br />
CCRefund, no matter the type of refund, accepts the following parameters:<br />
<br />
{{Template:PayTrace Optional Parameters}}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
PayTrace supports all five subscription functions. Creating and modifying subscriptions all accept a chargeDescription as an optional parameter.<br />
<br />
Valid pay periods include annually, semi-annually, trimesterly, quarterly, bi-monthly, monthly, bi-weekly, first-and-fifthteenth, weekly, and daily. The number of installments specify how many transactions to run. A six month subscription would specify a payPeriod of monthly, and 6 installments.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use '''CCCreateSubscriptionACH.''' You'll need to assign a customerProfileId that will be used for future subscription modifications.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|userName||userName<br />
|-<br />
|password||password<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||"";<br />
|-<br />
|startDate||accountHolderFirstName<br />
|-<br />
|payPeriod||accountHolderLastName<br />
|-<br />
|"";||"";<br />
|-<br />
|"customerProfileId="||numberOfInstallments<br />
|-<br />
| || startDate<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|-<br />
| || "customerProfileId="<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''. The optional parameters can be set to "" if you do not need to modify them. <br />
<br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big>|| <big>CCModifySubscriptionACH</big><br />
|-<br />
|userName||userName<br />
|-<br />
|password||password<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|''dollarAmount''||''dollarAmount''<br />
|-<br />
|''cardNumber''||''accountNumber''<br />
|-<br />
|''expirationDate''||''abaRoutingNumber''<br />
|-<br />
|"";||"";<br />
|-<br />
|''numberOfInstallments''||"";<br />
|-<br />
|''startDate''||''accountHolderFirstName''<br />
|-<br />
|''payPeriod"||''accountHolderLastName''<br />
|-<br />
|"";||"";<br />
|-<br />
|||''numberOfInstallments''<br />
|-<br />
| || ''startDate''<br />
|-<br />
| ||''payPeriod''<br />
|-<br />
| || "";<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|userName<br />
|-<br />
|password<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
==Payment Profiles==<br />
<br />
=== Creating Payment Profiles===<br />
<br />
Payment profiles allow you to save payment information straight to the gateway for future use. To create a payment profile, call either '''CCProfileCreatePayment''' or '''CCProfileCreatePaymentACH''', depending on whether the payment profile is a credit card or ACH. Credit cards are created with '''CCProfileCreatePayment''' and updated with '''CCProfileUpdatePayment'''. Italicized items are optional.<br />
<br />
To create a payment, pass in a customerProfileId, which is a unique ID you create and use for modifying or running payments.<br />
<br />
{| cellpadding="10"<br />
|-<br />
|<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePayment</big>|| <big>CCProfileUpdatePayment</big><br />
|-<br />
|userName||userName<br />
|-<br />
|password||password<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|cardNumber||""<br />
|-<br />
|expirationDate||''cardNumber''<br />
|-<br />
|"firstName="||''expirationDate''<br />
|-<br />
|"lastName="||''"firstName="''<br />
|-<br />
||||''"lastName="''<br />
|}<br />
|<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePaymentACH</big><br />
| <big>CCProfileUpdatePaymentACH</big><br />
|-<br />
|userName||userName<br />
|-<br />
|password||password<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|accountNumber||"";<br />
|-<br />
|routingNumber||''accountNumber''<br />
|-<br />
|"";||''routingNumber''<br />
|-<br />
|"";||"";<br />
|-<br />
|accountHolderFirstName||"";<br />
|-<br />
|accountHolderLastName||''accountHolderFirstName''<br />
|-<br />
|||''accountHolderLastName''<br />
|}<br />
|}<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
!Parameters<br />
|-<br />
|email||phone<br />
|-<br />
|fax||address<br />
|-<br />
|address2||city<br />
|-<br />
|state||zip<br />
|-<br />
|shipFirstName||shipLastName<br />
|-<br />
|shipAddress||shipAddress2<br />
|-<br />
|shipCity||shipState<br />
|-<br />
|shipZip||shipCountry<br />
|}<br />
</center><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
After creation, payments can be deleted with '''CCProfileDeletePayment'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileDeletePayment</big><br />
|-<br />
|userName<br />
|-<br />
|password<br />
|-<br />
|customerProfileId<br />
|-<br />
|"";<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
=== Running Charges Against Profiles ===<br />
<br />
You can process a payment, authorize a payment, capture an authorized payment, void, and refund transactions. Make sure to add the "methodOfPayment=ACH" or "methodOfPayment=CC" to each transaction, except authorized payments.<br />
<br />
If you want to run authorize only transactions, use '''CCProfileProcessPayment''' and add "authMode=AUTH_ONLY" to the list of parameters. To then capture that transaction, run '''CCProfileProcessAuthorizedPayment'''.<br />
<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
| <big>CCProfileProcessAuthorizedPayment</big><br />
| <big> CCProfileRefund </big><br />
| <big> CCProfileVoidPayment</big><br />
|-<br />
|userName||userName||userName||'userName<br />
|-<br />
|password||password||password||password<br />
|-<br />
|customerProfileId'||customerProfileId||customerProfileId||customerProfileId<br />
|-<br />
|"";||"";||"";||"";<br />
|-<br />
|dollarAmount||previousTransactionId||previousTransactionId||previousTransactionId<br />
|-<br />
|"methodOfPayment="||dollarAmount ''- pass in ""; if not needed'' ||"methodOfPayment="||amountToCredit<br />
|-<br />
||authMode|| || ||"";<br />
|}<br />
<br />
'''Returns''': Payments return a transaction ID from the payment gateway service if the transaction is successful, or "ERROR" if there was a problem. Refunds and voids will return 1 on success, or "ERROR" if there was a problem.<br />
<br />
CCProfileProcessPayment and CCProfileRefund accept the following parameters as well:<br />
<br />
{{Template:PayTrace Optional Parameters}}<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/MonerisMoneris2013-11-07T20:57:19Z<p>Sarah: /* Moneris */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==Moneris==<br />
<br />
The Moneris gateway supports running credit card transactions, authorize only transactions, and subscription payments. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [http://www.moneris.com/ Moneris Gateway], and use your '''store ID''' and the '''password''' as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of store ID and password. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
storeID;<br />
password; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value: CCSetGateway("Moneris") ]<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
Once you properly configure your merchant account, you can quickly and easily process payment transactions.<br />
You must provide the following information for a credit card payment transaction:<br />
* store ID<br />
* password<br />
* dollar amount <br />
* credit card number <br />
* credit card expiration date <br />
* order ID<br />
<br />
Moneris also requires an Order ID in combination with the standard requirements for the function. You can pass in this extra, required variable by adding "orderId=12432342" to the end of the statement.<br />
<br />
The CCProcessPayment function will process a transaction and return a transaction ID. This function returns a transaction ID if the transaction is successful or the word ERROR if the transaction fails. For detailed information about the most recent transaction failure, call the CCLastError function before calling any other transaction-processing function. In your script, you would then have a second line after setting the gateway.<br />
<br />
Set Variable $result Value: <br />
CCProcessPayment(<br />
storeId, <br />
password;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"orderId=213214321")<br />
<br />
'''Returns''': a verification code from the payment gateway service if the order is successful, or "ERROR" if there was a problem<br />
<br />
'''Note''': It is important to store the resulting transaction ID because you may need it later to void the transaction, issue a refund or capture a previously authorized transaction.<br />
<br />
You may submit optional parameters to most of Plastic's payment-transaction processing functions. These parameters will be submitted to the payment gateway along with the basic transaction information. Although they are not usually required to process an order, these parameters can be useful for tasks such as address verification or linking a transaction to a customer id or an invoice number. To supply additional parameters to a function call, add them to the end of the parameter list after the last required parameter, using a "key=value" syntax.<br />
<br />
Set Variable $result Value:<br />
CCProcessPayment(<br />
storeId,<br />
password;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"orderId=32432432";<br />
"chargeDescription=" & Transaction::Description;<br />
"verificationCode=" & $securityCode)<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|verificationCode <br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|companyName<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|-<br />
|shipAddress <br />
|the shipping street address<br />
|-<br />
|shipCity <br />
|the shipping address city<br />
|-<br />
|shipCompanyName <br />
|the shipping recipient's company name<br />
|-<br />
|shipCountry <br />
|the shipping address country<br />
|-<br />
|shipFirstName <br />
|the shipping recipient's first name<br />
|-<br />
|shipLastName <br />
|the shipping recipient's last name<br />
|-<br />
|shipState <br />
|the shipping address state<br />
|-<br />
|shipZip <br />
|the shipping address zip<br />
|}<br />
</center><br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
A sale transaction for credit card contains two parts: an ''authorization'' which verifies and places a hold for the amount, and a ''capture'', which actually transfers the funds.<br />
<br />
To run an authorization, pass in an additional parameter '''authMode=AUTH_ONLY'''.<br />
<br />
Set Variable $result Value:<br />
CCProcessPayment(<br />
storeId,<br />
password;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"orderId=32432432";<br />
authMode=AUTH_ONLY)<br />
<br />
After running an authorization, run the appropriate '''CCProcessAuthorizedPayment'''. Pass in the previousTransactionId from the transaction ID you received from the process with authMode.<br />
Set Variable [$result Value:<br />
CCProcessAuthorizedPayment (<br />
storeId,<br />
password;<br />
previousTransactionId;<br />
"orderId=32432432")<br />
<br />
'''Returns''': a verification code from the payment gateway service if the order is successful, or "ERROR" if there was a problem <br />
<br />
=== Partial Transactions===<br />
<br />
====Using "isPartailAuthroization=true" and splitTenderId====<br />
<br />
When using CCProcessPayment, specifying the additional parameter "authMode=AUTH_ONLY" will perform an authorization as opposed to a sale transaction. Specifying the "isPartialAuthorization=true" parameter will tell the gateway to allow for partial authorizations of pre-paid credit cards, gift cards and debit cards. Specifying the splitTenderId parameter tells the gateway that the amount authorized for the current transaction will be applied toward the remaining balance of a previous transaction identified by the split tender ID.<br />
<br />
When using CCProcessAuthorizedPayment, users can also pass in the splitTenderId instead of the previous transaction ID. This will capture the authorized amount from a previous transaction.<br />
<br />
====Charging the Outstanding Balance====<br />
<br />
After specifying a partial authorization, you can request the remaining balance and the requested amount by using CCPartialGetRemainingBalance and CCPartialGetRequestedAmount. Both return the dollar amounts, and do not require any additional parameters. You can also retrieve the splitTenderId with CCLastSplitTenderId.<br />
<br />
=== Voiding Transactions ===<br />
<br />
Set Variable [$result; Value: <br />
CCVoidPayment (<br />
storeId ;<br />
password ;<br />
previousTransactionID;<br />
"orderId=32432432")]<br />
<br />
Voids a previously processed payment. The parameters are similar to the CCProcessPayment function, except dollarAmount is replaced with the addition of the previousTransactionID parameter. The previousTransactionID should be the transaction ID of the transaction you wish to void. This value is returned by the CCProcessPayment function. Alternately, you can use the CCLastPaymentTransactionID function to get the transactionID of the last processed payment.<br />
<br />
Parameters:<br />
<br />
'''storeId''' - your payment gateway merchant account name<br />
<br />
'''password''' - your merchant account password OR transaction key.<br />
<br />
'''previousTransactionID''' - the transactionId of a previously processed transaction.<br />
<br />
Note that CCVoidPayment will only work on orders that have not settled yet, which means that it will generally only work on payments made that same day. To void settled orders, use CCRefund instead.<br />
<br />
'''Returns''': 1 on success, "ERROR" on failure.<br />
<br />
See also: CCLastPaymentTransactionIDReturns: the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem (use CCLastError for more detailed information about the nature of the error)<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
To credit a transaction, you need the transaction ID returned by CCProcessPayment. Pass this (along with other payment info) to the '''CCRefund''' function. This is similar to the void process, except it accepts a dollar amount and the credit card number (or the last four digits of the credit card number) used to process the original transaction.<br />
<br />
Set Variable [$result; Value:<br />
CCRefund( <br />
storeId; <br />
password; <br />
transactionID; <br />
cardNumber; <br />
dollarAmount;<br />
"orderId=32432432")] <br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with Moneris, pass in the blank transaction ID. and use CCRefund with the expiration date.<br />
<br />
<pre>Set Variable [$result Value:CCRefund(<br />
storeId,<br />
password;<br />
"";<br />
cardNumber;<br />
amountToCredit;<br />
"expirationDate=12/13";<br />
"orderId=32432432")]</pre><br />
<br />
'''Returns''': 1 on success, "ERROR" on failure.<br />
<br />
== Subscription Services ==<br />
<br />
With subscriptions, payments can automatically be debited to a credit card or a bank account on a time period you specify. Subscriptions are created with '''CCCreateSubscription''', and modified with '''CCModifySubscription'''. A successful subscription creation will return a subscription ID, which you can then use to modify or delete. <br />
<br />
Valid pay periods may include monthly, yearly and the like. Frequency indicates how often in that period. For example, a biweekly subscription would have a pay period of weekly and a frequency of 2. The number of installments specify how many transactions to run total.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big><br />
| <big>CCModifySubscription</big><br />
|-<br />
|'''storeId'''<br />
|'''storeId'''<br />
|-<br />
<br />
|'''password'''<br />
|'''password'''<br />
|-<br />
|'''dollarAmount'''<br />
|'''previousSubscriptionId'''<br />
|-<br />
| '''cardNumber''' <br />
| '''dollarAmount''' //Optional, pass ""; if not needed <br />
|-<br />
| '''expirationDate''' <br />
| '''cardNumber''' //Optional <br />
|-<br />
| '''""''' <br />
| '''expirationDate''' //Optional <br />
|-<br />
| '''numberOfInstallments''' <br />
| '''""''' <br />
|-<br />
| '''startDate''' <br />
| '''numberOfInstallments''' //Optional <br />
|-<br />
| '''payPeriod'''<br />
| '''"";'''<br />
|-<br />
| '''frequency''' <br />
| '''"";''' <br />
|-<br />
|''' "orderId=1232313"''' <br />
| '''"";''' <br />
|-<br />
| trialAmount*<br />
| orderId<br />
|-<br />
| verificationCode<br />
| customerId<br />
|-<br />
|customerId <br />
|-<br />
|firstName <br />
|-<br />
|lastName <br />
|-<br />
|email <br />
|-<br />
|fax <br />
|-<br />
|companyName<br />
|-<br />
|phone<br />
|-<br />
|address<br />
|-<br />
|city <br />
|-<br />
|state <br />
|-<br />
|zip <br />
|-<br />
|country <br />
|-<br />
|shipAddress <br />
|-<br />
|shipCity <br />
|-<br />
|shipCompanyName <br />
|-<br />
|shipCountry <br />
|-<br />
|shipFirstName <br />
|-<br />
|shipLastName <br />
|-<br />
|shipState <br />
|-<br />
|shipZip<br />
|}<br />
<br />
'''Returns''': CCCreateSubscription will return the subscription ID on success, "ERROR" on failure. CCModifySubscription will return 1 on success, "ERROR" on failure.<br />
<br />
If you specify a trialAmount, the a charge will be performed for the trialAmount prior to the start of the subscription.<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|storeId<br />
|-<br />
|password<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, "ERROR" on failure.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/Merchant_WarriorMerchant Warrior2013-11-07T20:57:05Z<p>Sarah: /* Merchant Warrior */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==Merchant Warrior==<br />
<br />
Merchant Warrior supports card not present and authorize only transactions, as well as payment profiles, saving payment methods directly and securely with your gateway. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [https://www.merchantwarrior.com/join Merchant Warrior Gateway], and use your '''Merchant UUID''' and the '''API Key''' as the first two parameters for every plug-in function call that performs a transaction. You'll also need your API pass phrase, passed as an additional but required parameter. These values should be given to you once you sign up for a Merchant Warrior account. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of Merchant UUID and API Key. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantUUID, <br />
apiKey;<br />
"apiPassPhrase="; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("Merchant Warrior")] CCSetGateway("Merchant Warrior")<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
Once you properly configure your merchant account, you can quickly and easily process payment transactions.<br />
<br />
You must provide the following information for a credit card payment transaction:<br />
*Merchant UUID <br />
*API Key <br />
*Dollar amount<br />
*Credit card number<br />
*Credit card expiration date<br />
*API Pass Phrase<br />
*Currency<br />
*Charge description<br />
*First name<br />
*Last name<br />
*Billing city<br />
*Billing state<br />
*Billing zip<br />
*Billing country<br />
<br />
Returns: the CCProcessPayment function will process a transaction and return a transaction ID. This function returns a transaction ID if the transaction is successful or the word ERROR if the transaction fails. For detailed information about the most recent transaction failure, call the CCLastError function before calling any other transaction-processing function.<br />
<br />
In your script, you would then have a second line after setting the gateway.<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessPayment(<br />
merchantUUID, <br />
apiKey;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"apiPassPhrase=";<br />
"currency=";<br />
"chargeDescription=";<br />
"firstName=";<br />
'lastName=";<br />
"city=";<br />
"state=";<br />
"zip=";<br />
"country=")<br />
</pre><br />
<br />
'''Note''': It is important to store the resulting transaction ID because you may need it later to void the transaction, issue a refund or capture a previously authorized transaction.<br />
<br />
You may submit optional parameters to most of Plastic's payment-transaction processing functions. These parameters will be submitted to the payment gateway along with the basic transaction information. Although they are not usually required to process an order, these parameters can be useful for tasks such as address verification or linking a transaction to a customer id or an invoice number. To supply additional parameters to a function call, add them to the end of the parameter list after the last required parameter, using a "key=value" syntax.<br />
<br />
<pre>Set Variable $result Value:<br />
CCProcessPayment(<br />
merchantUUID, <br />
apiKey;<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"apiPassPhrase=";<br />
"currency=";<br />
"chargeDescription=";<br />
"firstName=";<br />
'lastName=";<br />
"city=";<br />
"state=";<br />
"zip=";<br />
"country="<br />
"email=" & Payment::Email;<br />
"verificationCode=" & $securityCode)</pre><br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|email<br />
|the billing address street address<br />
|-<br />
|phone<br />
|the billing phone number<br />
|-<br />
|verificationCode<br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|}<br />
</center><br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
A sale transaction for credit card contains two parts: an ''authorization'' which verifies and places a hold for the amount, and a ''capture'', which actually transfers the funds.<br />
<br />
To run an authorization, pass in an additional parameter '''authMode=AUTH_ONLY'''.<br />
<pre>Set Variable $result Value: CCProcessPayment(merchantUUID, apiKey;chargeAmount;cardNumber;expDate;<br />
"apiPassPhrase=";<br />
"currency=";<br />
"chargeDescription=";<br />
"firstName=";<br />
'lastName=";<br />
"city=";<br />
"state=";<br />
"zip=";<br />
"country="<br />
"email=" & Payment::Email;<br />
"verificationCode=" & $securityCode;<br />
authMode=AUTH_ONLY)</pre>After running an authorization, run the appropriate '''CCProcessAuthorizedPayment'''. Pass in the previousTransactionId from the transaction ID you received from the process with authMode.<br />
Set Variable $result Value: CCProcessAuthorizedPayment(merchantUUID, apiKey;previousTransactionId;dollarAmount;<br />
"apiPassPhrase=";<br />
"currency=")<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
To credit a transaction, you need the transaction ID returned by CCProcessPayment. Pass this (along with other payment info) to the CCRefund function.<br />
<br />
<pre><br />
Set Variable [$result; Value:<br />
CCRefund(<br />
merchantUUID;<br />
apiKey;<br />
transactionID;<br />
cardNumber;<br />
dollarAmount; //Optional<br />
"apiPassPhrase=")]<br />
</pre><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
Optionally, you may pass in currency as a parameter. Card number is not required for a refund, you may pass ""; if not required.<br />
<br />
== Payment Profiles==<br />
<br />
Plastic 2 features payment profiles, which allow you to submit payment information to be reused for future transactions. This greatly simplifies PCI compliance, and keeps sensitive information out of your database.<br />
<br />
To create a payment profile, call '''CCProfileCreatePayment'''. This function will return a profile ID to use if successful. Pass in a first name and a last name using the key=value syntax. To modify a payment you've previously created, use '''CCProfileUpdatePayment'''. <br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePayment</big><br />
| <big>CCProfileUpdatePayment</big><br />
|-<br />
|merchantUUIDName<br />
|merchantUUIDName<br />
|-<br />
|apiKey<br />
|apiKey<br />
|-<br />
|""<br />
|""<br />
|-<br />
|cardNumber<br />
|paymentProfileId<br />
|-<br />
|expirationDate<br />
|""<br />
|-<br />
|"firstName="<br />
|expirationDate<br />
|-<br />
|"lastName="<br />
|<br />
|}<br />
<br />
'''Returns''': CCProfileCreatePayment returns the profile ID if successful. CCProfileUpdatePayment will return 1 on success, or "ERROR" if there was a problem.<br />
<br />
After a payment has been created, it can be retrieved with CCProfileGetPayment. To delete a payment, use CCProfileDeletePayment.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileGetPayment</big><br />
| <big>CCProfileDeletePayment</big><br />
|-<br />
|merchantUUIDName<br />
|merchantUUIDName<br />
|-<br />
|apiKey<br />
|apiKey<br />
|-<br />
|""<br />
|""<br />
|-<br />
|paymentProfileId<br />
|paymentProfileId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
{{Template:Profiles}}<br />
<br />
=== Running Charges Against Profiles ===<br />
After the profile has been saved to the gateway, use the Profile ID it returns to run a charge without having to rekey card data. For this, we use '''CCProfileProcessPayment'''.<br />
<br />
<br />
<pre>Set Variable $result Value:CCProfileProcessPayment(<br />
merchantUUID, <br />
apiKey;<br />
"";<br />
paymentProfileId;<br />
dollarAmount;<br />
"apiPassPhrase=";<br />
"currency=";<br />
"chargeDescription=";<br />
"firstName=";<br />
'lastName=";<br />
"city=";<br />
"state=";<br />
"zip=";<br />
"country=")</pre><br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|email<br />
|the billing address street address<br />
|-<br />
|phone<br />
|the billing phone number<br />
|-<br />
|verificationCode<br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|}<br />
</center><br />
<br />
'''Returns''': a transaction ID from the payment gateway service if the transaction is successful, or "ERROR" if there was a problem.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/Merchant_eSolutionsMerchant eSolutions2013-11-07T20:56:48Z<p>Sarah: /* Merchant eSolutions */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
== Merchant eSolutions==<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [https://www.merchante-solutions.com/merchants/merchant_contact.html Merchant eSolutions Gateway], and use your '''profile ID''' and the '''profile key''' as the first two parameters for every plug-in function call that performs a transaction. The profile ID identifies the source of the incoming request, and the profile key specifies the API password assigned to the specified profile identifier. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of profile ID and profile key. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
profileID;<br />
profileKey; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. If you have a card present account, you should also pass in the card present parameter.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("Merchant eSolutions"; "cardPresent=true")]<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
{{Template:Processing Payments|profileID|profileKey}}<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|verificationCode<br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|-<br />
|invoiceNumber<br />
|an arbitrary invoice number for your records<br />
|-<br />
|orderId<br />
|an arbitrary order number for your records<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|zip<br />
|the billing zip code<br />
|}<br />
</center><br />
<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|profileID|profileKey}}<br />
<br />
<pre>Set Variable $result Value: CCProcessAuthorizedPayment(<br />
profileID;<br />
profileKey;<br />
previousTransactionId;<br />
dollarAmount;<br />
"invoiceNumber=" //Optional)</pre><br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
For Merchant eSolutions, you can pass either the swipe, track1, or track2.<br />
<br />
<pre>Set Variable [$result; Value:CCProcessPayment(<br />
profileID;<br />
profileKey;<br />
chargeAmount;<br />
"";<br />
"";<br />
"swipe=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]</pre><br />
<br />
===Partial Transactions===<br />
<br />
When using CCProcessPayment, specifying the additional parameter "authMode=AUTH_ONLY" will perform an authorization as opposed to a sale transaction. Specifying the "isPartialAuthorization=true" parameter will tell the gateway to allow for partial authorizations of pre-paid credit cards, gift cards and debit cards. <br />
<br />
After specifying a partial authorization, you can request the remaining balance and the requested amount by using CCPartialGetRemainingBalance and CCPartialGetRequestedAmount. Both return the dollar amounts, and do not require any additional parameters. <br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|profileID|profileKey}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|profileID|profileKey}}<br />
<br />
== Payment Profiles ==<br />
<br />
Payment profiles allow you to save payment information straight to the gateway for future use. To create a payment profile, call '''CCProfileCreatePayment.''' The available optional parameters are listed below. To delete a payment, use '''CCProfileDeletePayment''' with no optional parameters.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePayment</big><br />
| <big>CCProfileDeletePayment</big><br />
|-<br />
|profileId<br />
|profileId<br />
|-<br />
|profileKey<br />
|profileKey<br />
|-<br />
|""<br />
|""<br />
|-<br />
|paymentProfileId<br />
|paymentProfileId<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|verificationCode<br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|-<br />
|invoiceNumber<br />
|an arbitrary invoice number for your records<br />
|-<br />
|orderId<br />
|an arbitrary order number for your records<br />
|-<br />
|customerId<br />
|an arbitrary customer number for your records<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|zip<br />
|the billing zip code<br />
|}<br />
</center><br />
<br />
'''Returns''': Creating a payment will return the ID of the profile created, "ERROR" on failure. Deleting will return 1 on success, "ERROR" on failure.<br />
<br />
=== Running Charges Against Profiles ===<br />
<br />
You can process a payment, authorize a payment, capture an authorized payment, void, and refund transactions. If you want to run authorize only transaction, use '''CCProfileProcessPayment''' and add "authMode=AUTH_ONLY" to the list of parameters. To then capture that transaction, run '''CCProfileProcessAuthorizedPayment'''.<br />
<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
| <big>CCProfileProcessAuthorizedPayment</big><br />
| <big> CCProfileVoidPayment</big><br />
| <big> CCProfileRefund </big><br />
|-<br />
|'''profileId'''<br />
|'''profileId'''<br />
|'''profileId'''<br />
|'''profileId'''<br />
|-<br />
|'''profileKey'''<br />
|'''profileKey'''<br />
|'''profileKey'''<br />
|'''profileKey'''<br />
|-<br />
|'''""'''<br />
|'''""'''<br />
|'''""'''<br />
|'''""'''<br />
|-<br />
|'''paymentProfileId'''<br />
|'''paymentProfileId'''<br />
|'''paymentProfileId'''<br />
|'''paymentProfileId'''<br />
|-<br />
|'''dollarAmount'''<br />
|'''previousTransactionId'''<br />
|'''previousTransactionId'''<br />
|'''previousTransactionId'''<br />
|-<br />
|authMode<br />
|'''dollarAmount'''<br />
|<br />
|'''amountToCredit'''<br />
|-<br />
|verificationCode<br />
|invoiceNumber<br />
|<br />
|'''""'''<br />
|-<br />
|invoiceNumber<br />
|<br />
|<br />
|<br />
|-<br />
|orderId<br />
|<br />
|<br />
|<br />
|-<br />
|customerId<br />
|<br />
|<br />
|<br />
|-<br />
|address<br />
|<br />
|<br />
|<br />
|-<br />
|zip<br />
|<br />
|<br />
|<br />
|}<br />
<br />
'''Returns''': Payments return a transaction ID from the payment gateway service if the transaction is successful, or "ERROR" if there was a problem. Refunds and voids will return 1 on success, or "ERROR" if there was a problem.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/InternetSecureInternetSecure2013-11-07T20:56:27Z<p>Sarah: /* InternetSecure */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==InternetSecure==<br />
<br />
InternetSecure can process a wide variety of transactions, including authorization only, card swipes, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [http://www.internetsecure.com/apply.htm InternetSecure Gateway], and use your '''merchant account''' the first parameter for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key;'' this is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. You should pass in a blank value for the transaction key, as follows:<br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantAccount;<br />
""; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
CCSetGateway("InternetSecure")<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
Once you properly configure your merchant account, you can quickly and easily process payment transactions.<br />
<br />
You must provide the following information for a credit card payment transaction:<br />
*merchant account <br />
*dollar amount<br />
*credit card number<br />
*credit card expiration date<br />
<br />
The CCProcessPayment function will process a transaction and return a transaction ID. This function returns a transaction ID if the transaction is successful or the word ERROR if the transaction fails. For detailed information about the most recent transaction failure, call the CCLastError function before calling any other transaction-processing function.<br />
<br />
In your script, you would then have a second line after setting the gateway. Note the second parameter remains blank, as tranactionKeys are not required when using Internet Secure. <br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessPayment(<br />
merchantAccount, <br />
"";<br />
chargeAmount;<br />
cardNumber;<br />
expDate)<br />
</pre><br />
<br />
'''Note''': It is important to store the resulting transaction ID because you may need it later to void the transaction, issue a refund or capture a previously authorized transaction.<br />
<br />
You may submit optional parameters to most of Plastic's payment-transaction processing functions. These parameters will be submitted to the payment gateway along with the basic transaction information. Although they are not usually required to process an order, these parameters can be useful for tasks such as address verification or linking a transaction to a customer ID or an invoice number. To supply additional parameters to a function call, add them to the end of the parameter list after the last required parameter, using a "key=value" syntax.<br />
<br />
<pre>Set Variable $result Value:<br />
CCProcessPayment(<br />
merchantAccount, <br />
"";<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
"chargeDescription=" & Payment::description;<br />
"customerId=" & $custID)</pre><br />
<br />
{{Template:InternetSecure Optional Parameters}}<br />
<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
A sale transaction for credit card contains two parts: an ''authorization'' which verifies and places a hold for the amount, and a ''capture'', which actually transfers the funds.<br />
<br />
To run an authorization, pass in an additional parameter '''authMode=AUTH_ONLY'''.<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessPayment(<br />
merchantAccount, <br />
"";<br />
chargeAmount;<br />
cardNumber;<br />
expDate;<br />
authMode=AUTH_ONLY)<br />
</pre><br />
<br />
After running an authorization, call '''CCProcessAuthorizedPayment.''' Pass in the previousTransactionId from the transaction ID you received from the process with authMode. The dollarAmount is not required to process the authorized payment. <br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessAuthorizedPayment(<br />
merchantAccount, <br />
"";<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre><br />
<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
merchantAccount;<br />
"";<br />
chargeAmount;<br />
"";<br />
"";<br />
"track2=;1234123412341234=11121010000000000111?")]<br />
</pre><br />
<br />
{{Template:InternetSecure Optional Parameters}}<br />
<br />
=== Voiding Transactions ===<br />
<br />
<pre>Set Variable [$result; Value: CCVoidPayment ( merchantAccount ; "" ; previousTransactionID)]</pre><br />
<br />
Voids a previously processed payment. The parameters are similar to the CCProcessPayment function, except dollarAmount is replaced with the addition of the previousTransactionID parameter. The previousTransactionID should be the transaction ID of the transaction you wish to void. This value is returned by the CCProcessPayment function. Alternately, you can use the CCLastPaymentTransactionID function to get the transactionID of the last processed payment.<br />
<br />
Note that CCVoidPayment will only work on orders that have not settled yet, which means that it will generally only work on payments made that same day. To void settled orders, use CCRefund instead.<br />
<br />
See also: CCLastPaymentTransactionIDReturns: the transactionID from the payment gateway service if the order is successful, or "ERROR" if there was a problem (use CCLastError for more detailed information about the nature of the error)<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
To credit a transaction, you need the transaction ID returned by CCProcessPayment. Pass this (along with other payment info) to the CCRefund function. This is similar to the void process, except it accepts a dollar amount used to process the original transaction, and will refund orders that have already settled.<br />
Set Variable [$result; Value: <br />
CCRefund( <br />
merchantAccount ; <br />
"" ; <br />
previousTransactionId ; <br />
""; <br />
2.99 ; // the amount of the refund <br />
"chargeDescription=")<br />
<br />
Please note that the transaction key and card number are left blank, as they are not used with InternetSecure.<br />
<br />
==Subscription Services==<br />
<br />
With subscriptions, payments can automatically be debited to a credit card or a bank account on a time period you specify. To create a credit card subscription, use '''CCCreateSubscription.''' <br />
<br />
Valid pay periods include daily, weekly, biweekly, monthly, bimonthly, quarterly, semiannually, and annually. The number of installments specify how many transactions to run. A six month subscription would specify a payPeriod of monthly, and 6 installments.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big><br />
|-<br />
|merchantAccount<br />
|-<br />
|"";<br />
|-<br />
|dollarAmount<br />
|-<br />
|cardNumber<br />
|-<br />
|expDate<br />
|-<br />
|"":<br />
|-<br />
|numberOfInstallments<br />
|-<br />
|startDate<br />
|-<br />
|payPeriod<br />
|-<br />
|"";<br />
|}<br />
<br />
{{Template:InternetSecure Optional Parameters}}<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|merchantAccount<br />
|-<br />
|""<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/FirstDataFirstData2013-11-07T20:56:02Z<p>Sarah: </p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==First Data==<br />
<br />
First Data can process a wide variety of transactions, including card swipes, eCheck / ACH payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [https://www.firstdata.com/en_us/home.html First Data Gateway], and use your '''user ID''' and the '''password''' as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of user ID and password. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
userID;<br />
password; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. If you have a card present account, pass in cardPresent=true.<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("First Data"; "cardPresent=true")]</pre><br />
<br />
'''Returns''': 1 if a valid gateway is provided, ERROR otherwise.<br />
<br />
As a First Data customer, you'll be supplied with a security certificate. To use this, you can put your certificate in a container field and call the following function:<br />
<br />
<pre>Set Variable [$cert; Value:CCSetCertificate ( certificate ; password )]</pre><br />
<br />
'''Returns''': 1 if a valid certificate is provided, ERROR otherwise.<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
{{Template:Emulators}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
{{Template:Processing Payments|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
=== Processing ACH payments ===<br />
<br />
{{Template:Processing ACH payments|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
<pre>Set Variable $result Value:<br />
CCProcessAuthorizedPayment(<br />
userID,<br />
password;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre><br />
<br />
The dollarAmount is not required to process the authorized payment.<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
userID;<br />
password;<br />
chargeAmount;<br />
"";<br />
"";<br />
"swipe=%B1234123412341234^LAST/FIRSTM^1112101000000000011100111000000?;1234123412341234=11121010000000000111?")]<br />
</pre><br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|userID|password}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with First Data, pass in the blank transaction ID. It will be a little different based on whether it was a swiped or a typed card:<br />
<br />
{|<br />
<br />
|-<br />
<br />
|''Card Not Present Unlinked Refund''<br />
<br />
|''Card Present Unlinked Refund''<br />
|-<br />
| <pre>Set Variable $result Value:<br />
CCRefund(<br />
userID,<br />
password;<br />
"";<br />
cardNumber;<br />
amountToCredit;<br />
"expirationDate=12/13")<br />
</pre><br />
<br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
userID,<br />
password;<br />
"";<br />
"";<br />
amountToCredit;<br />
"swipe=")<br />
</pre><br />
<br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
First Data supports all five subscription functions. Creating and modifying subscriptions all accept the same optional parameters, available in the table below.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use CCCreateSubscriptionACH. Do not pass in a subscription name. You'll also need to set a maximum number of failures using the key=value syntax.<br />
<br />
Valid pay periods may include monthly, yearly and the like. Frequency indicates how often in that period. For example, a biweekly subscription would have a pay period of weekly and a frequency of 2. The number of installments specify how many transactions to run total.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big><br />
| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|userID||userID<br />
|-<br />
|password||password<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||"";<br />
|-<br />
|payPeriod||"";<br />
|-<br />
|frequency||"";<br />
|-<br />
|"maximumFailures="||numberOfInstallments<br />
|-<br />
|||startDate<br />
|-<br />
|||payPeriod<br />
|-<br />
|||frequency<br />
|-<br />
|||"maximumFailures="<br />
|-<br />
|||"driversLicenseNumber="<br />
|-<br />
|||"driversLicenseState<br />
|}<br />
<br />
'''Returns''': a subscription ID if the subscription has been successful, "ERROR" if there was a problem.<br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big><br />
| <big>CCModifySubscriptionACH</big><br />
|-<br />
|userID||userID<br />
|-<br />
|password||password<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|dollarAmmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||"";<br />
|-<br />
|payPeriod||"";<br />
|-<br />
|frequency||"";<br />
|-<br />
|"maximumFailures="||numberOfInstallments<br />
|-<br />
|||startDate<br />
|-<br />
|||payPeriod<br />
|-<br />
|||frequency<br />
|-<br />
|||"maximumFailures="<br />
|}<br />
<br />
Modifying and creating subscriptions accepts the following:<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|userID<br />
|-<br />
|password<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/FirstDataFirstData2013-11-07T20:55:32Z<p>Sarah: /* First Data */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==First Data==<br />
<br />
First Data can process a wide variety of transactions, including card swipes, eCheck / ACH payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [https://www.firstdata.com/en_us/home.html First Data Gateway], and use your '''user ID''' and the '''password''' as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of user ID and password. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
userID;<br />
password; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. If you have a card present account, pass in cardPresent=true.<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("First Data"; "cardPresent=true")]</pre><br />
<br />
'''Returns''': 1 if a valid gateway is provided, ERROR otherwise.<br />
<br />
As a First Data customer, you'll be supplied with a security certificate. To use this, you can put your certificate in a container field and call the following function:<br />
<br />
<pre>Set Variable [$cert; Value:CCSetCertificate ( certificate ; password )]</pre><br />
<br />
'''Returns''': 1 if a valid certificate is provided, ERROR otherwise.<br />
<br />
{{Template:Emulators}}<br />
<br />
===Test Mode===<br />
<br />
{{Template:Test Mode}}<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
{{Template:Processing Payments|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
=== Processing ACH payments ===<br />
<br />
{{Template:Processing ACH payments|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
<pre>Set Variable $result Value:<br />
CCProcessAuthorizedPayment(<br />
userID,<br />
password;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre><br />
<br />
The dollarAmount is not required to process the authorized payment.<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
userID;<br />
password;<br />
chargeAmount;<br />
"";<br />
"";<br />
"swipe=%B1234123412341234^LAST/FIRSTM^1112101000000000011100111000000?;1234123412341234=11121010000000000111?")]<br />
</pre><br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|userID|password}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|userID|password}}<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with First Data, pass in the blank transaction ID. It will be a little different based on whether it was a swiped or a typed card:<br />
<br />
{|<br />
<br />
|-<br />
<br />
|''Card Not Present Unlinked Refund''<br />
<br />
|''Card Present Unlinked Refund''<br />
|-<br />
| <pre>Set Variable $result Value:<br />
CCRefund(<br />
userID,<br />
password;<br />
"";<br />
cardNumber;<br />
amountToCredit;<br />
"expirationDate=12/13")<br />
</pre><br />
<br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
userID,<br />
password;<br />
"";<br />
"";<br />
amountToCredit;<br />
"swipe=")<br />
</pre><br />
<br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
First Data supports all five subscription functions. Creating and modifying subscriptions all accept the same optional parameters, available in the table below.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use CCCreateSubscriptionACH. Do not pass in a subscription name. You'll also need to set a maximum number of failures using the key=value syntax.<br />
<br />
Valid pay periods may include monthly, yearly and the like. Frequency indicates how often in that period. For example, a biweekly subscription would have a pay period of weekly and a frequency of 2. The number of installments specify how many transactions to run total.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big><br />
| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|userID||userID<br />
|-<br />
|password||password<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||"";<br />
|-<br />
|payPeriod||"";<br />
|-<br />
|frequency||"";<br />
|-<br />
|"maximumFailures="||numberOfInstallments<br />
|-<br />
|||startDate<br />
|-<br />
|||payPeriod<br />
|-<br />
|||frequency<br />
|-<br />
|||"maximumFailures="<br />
|-<br />
|||"driversLicenseNumber="<br />
|-<br />
|||"driversLicenseState<br />
|}<br />
<br />
'''Returns''': a subscription ID if the subscription has been successful, "ERROR" if there was a problem.<br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big><br />
| <big>CCModifySubscriptionACH</big><br />
|-<br />
|userID||userID<br />
|-<br />
|password||password<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|dollarAmmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||"";<br />
|-<br />
|payPeriod||"";<br />
|-<br />
|frequency||"";<br />
|-<br />
|"maximumFailures="||numberOfInstallments<br />
|-<br />
|||startDate<br />
|-<br />
|||payPeriod<br />
|-<br />
|||frequency<br />
|-<br />
|||"maximumFailures="<br />
|}<br />
<br />
Modifying and creating subscriptions accepts the following:<br />
<br />
{{Template:FirstData Optional Parameters}}<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|userID<br />
|-<br />
|password<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/Template:Test_ModeTemplate:Test Mode2013-11-07T20:55:12Z<p>Sarah: Created page with "To run test transactions, call <code>CCSetTestMode</code> - If set to 1, tells Plastic to perform all subsequent transactions as test transactions. If set to 0, tells Plastic ..."</p>
<hr />
<div>To run test transactions, call <code>CCSetTestMode</code> - If set to 1, tells Plastic to perform all subsequent transactions as test transactions. If set to 0, tells Plastic to perform all subsequent transactions as live transactions. If this function is never called, the default behavior of Plastic is to treat all transactions as live transactions.</div>Sarahhttp://docs.360works.com/index.php/Authorize.NetAuthorize.Net2013-11-05T23:05:48Z<p>Sarah: /* Getting Response Information and Using Helper Functions */</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==Authorize.Net==<br />
<br />
Authorize.Net can process a wide variety of transactions, and supports eCheck / ACH payments, profile-based payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
If you do not already have a gateway or merchant account, you can sign up for an Authorize.Net account at the following:<br />
<br />
<center>[https://ems.authorize.net/oap/home.aspx?SalesRepID=98&ResellerID=11334 http://www.authorize.net/images/reseller/oap_sign_up.gif]</center><br />
<br />
You'll need an account using the [https://ems.authorize.net/oap/home.aspx?SalesRepID=98&ResellerID=11334 Authorize.Net Gateway], and use your '''Merchant API Login ID''' and the '''Merchant Transaction Key''' as the first two parameters for every plug-in function call that performs a transaction. The merchant API Login ID is provided in the Merchant Interface from Authorize.Net, and together with the transaction key provides the merchant authentication required for access to the payment gateway. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key''; this is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantAPILoginID;<br />
merchantTransactionKey; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before calling any function in Plastic, the first required step is to set the gateway required.<br />
<br />
Please note that Authorize.Net is the default payment gateway, so there is no need to use CCSetGateway. If you are a merchant who has a card-present account, then you should use the following function first:<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("Authorize.Net"; "cardPresent=true")]</pre><br />
<br />
'''Returns''': 1 if a valid gateway is provided, ERROR otherwise.<br />
<br />
{{Template:Emulators}}<br />
<br />
===Using Your Own Test Account===<br />
<br />
The Plastic demo database entitled How To Use Plastic comes with Authorize.Net test account credentials that may be used to test the functionality of the plugin. If you wish to use your own test account you must use the aforementioned alternate URL syntax. The URL you use depends on whether you want to perform standard transactions, profile transactions or subscription transactions.<br />
<br />
====Standard Transactions====<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("Authorize.Net"; "url=https://test.authorize.net/gateway/transact.dll")]</pre><br />
<br />
====Profile and Subscription Transactions====<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("Authorize.Net"; "url=https://apitest.authorize.net/soap/v1/Service.asmx")]</pre><br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
{{Template:Processing Payments|{{ANma}}|{{ANpw}}}}<br />
<br />
{{Template:AuthorizeNet Optional Parameters}}<br />
<br />
=== Processing ACH Payments ===<br />
<br />
{{Template:Processing ACH payments|{{ANma}}|{{ANpw}}}}<br />
<br />
For Authorize.NET payments, you MUST also pass in an achType as a key value parameter. You don't necessarily need to pass bankName, accountType, accountHolderFirstName, and accountHolderLastName. If you do not have that information, you can pass in a blank value with "";<br />
<br />
If taking a Account Receivable Transaction (ARC) or Back Office Conversion (BOC) payment, you must also pass in a check number. If not, simply type ""; where that checkNumber field would be. <br />
{{Template:AuthorizeNet Optional Parameters}}<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|{{ANma}}|{{ANpw}}}}<br />
<br />
Set Variable [$result Value: <br />
CCProcessAuthorizedPayment(<br />
{{ANma}};<br />
{{ANpw}};<br />
previousTransactionId;<br />
dollarAmount)]<br />
<br />
<br />
The dollarAmount is not required to process the authorized payment. CCProcessAuthorizedPayment accepts the same optional parameters as CCProcessPayment.<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
Set Variable [$result; Value:<br />
CCProcessPayment(<br />
{{ANma}};<br />
{{ANpw}};<br />
chargeAmount;<br />
"";<br />
"";<br />
"track1=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
<br />
=== Partial Transactions === <br />
<br />
====Using "isPartailAuthroization=true" and splitTenderId====<br />
<br />
When using CCProcessPayment, specifying the additional parameter "authMode=AUTH_ONLY" will perform an authorization as opposed to a sale transaction. Specifying the "isPartialAuthorization=true" parameter will tell the gateway to allow for partial authorizations of pre-paid credit cards, gift cards and debit cards. Specifying the splitTenderId parameter tells the gateway that the amount authorized for the current transaction will be applied toward the remaining balance of a previous transaction identified by the split tender ID.<br />
<br />
When using CCProcessAuthorizedPayment, users can also pass in the splitTenderId instead of the previous transaction ID. This will capture the authorized amount from a previous transaction.<br />
<br />
====Charging the Outstanding Balance====<br />
<br />
After specifying a partial authorization, you can request the remaining balance and the requested amount by using CCPartialGetRemainingBalance and CCPartialGetRequestedAmount. Both return the dollar amounts, and do not require any additional parameters. You can also retrieve the splitTenderId with CCLastSplitTenderId.<br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|{{ANma}}|{{ANpw}}}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|{{ANma}}|{{ANpw}}}}<br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with Authorize.Net, pass in the blank transaction ID. It will be a little different based on whether it was a swiped or a typed card:<br />
<br />
{|<br />
|-<br />
|''Card Not Present Unlinked Refund''<br />
|''Card Present Unlinked Refund''<br />
|-<br />
||<br />
Set Variable [$result Value:<br />
CCRefund(<br />
{{ANma}};<br />
{{ANpw}};<br />
"";<br />
cardNumber;<br />
chargeAmount;<br />
"expirationDate=12/13")]<br />
||<br />
Set Variable [$result Value:<br />
CCRefund(<br />
{{ANma}};<br />
{{ANpw}};<br />
"";<br />
"";<br />
chargeAmount;<br />
"track1=";<br />
"track2=")]<br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
Authorize.Net supports all five subscription functions. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. <br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use '''CCCreateSubscriptionACH.''' Italicized items are optional.<br />
<br />
Valid pay periods include days or months. Frequency indicates how often in that period. For example, a biweekly subscription would have a pay period of weekly and a frequency of 2. <br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|{{ANma}}||{{ANma}}<br />
|-<br />
|{{ANpw}}||{{ANpw}}<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|''subscriptionName''||''bankName''<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||accountHolderFirstName<br />
|-<br />
|payPeriod||accountHolderLastName<br />
|-<br />
|frequncy||''subscriptionName''<br />
|-<br />
|||numberOfInstallments<br />
|-<br />
| || startDate<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || frequency<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''. The optional parameters can be set to "" if you do not need to modify them. The last two, marked with ""; are payPeriod and frequency, which cannot be modified. <br />
<br />
The trialOccurrences parameter can only be updated if the trial period has not begun or is in progress.<br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|{{ANma}}||{{ANma}}<br />
|-<br />
|{{ANpw}}||{{ANpw}}<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|''dollarAmount''||''dollarAmount''<br />
|-<br />
|''cardNumber''||''accountNumber''<br />
|-<br />
|''expirationDate''||''abaRoutingNumber''<br />
|-<br />
|''subscriptionName''||''bankName''<br />
|-<br />
|''numberOfInstallments''||''accountType''<br />
|-<br />
|''startDate''||''accountHolderFirstName''<br />
|-<br />
|"";||''accountHolderLastName''<br />
|-<br />
|"";||''subscriptionName''<br />
|-<br />
|||''numberOfInstallments''<br />
|-<br />
| || ''startDate''<br />
|-<br />
| ||"";<br />
|-<br />
| || "";<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying subscriptions:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|trialOccurrences <br />
|The number of installments includes any trial occurrences. If you specify a trial occurrence, you must also specify a trialAmount.<br />
|-<br />
|trialAmount <br />
|If you specify a trial amount, you must also specify the trialOccurrences.<br />
|-<br />
|verificationCode <br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|-<br />
|invoiceNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|companyName <br />
|the billing company name<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|-<br />
|shipAddress <br />
|the shipping street address<br />
|-<br />
|shipCity <br />
|the shipping address city<br />
|-<br />
|shipCompanyName <br />
|the shipping recipient's company name<br />
|-<br />
|shipCountry <br />
|the shipping address country<br />
|-<br />
|shipFirstName <br />
|the shipping recipient's first name<br />
|-<br />
|shipLastName <br />
|the shipping recipient's last name<br />
|-<br />
|shipState <br />
|the shipping address state<br />
|-<br />
|shipZip <br />
|the shipping address zip<br />
|}<br />
</center><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|merchantAccountName<br />
|-<br />
|transactionKey<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
== Payment Profiles ==<br />
<br />
{{Template:Customer profiles|{{ANma}}|{{ANpw}}}}<br />
{{Template:Profiles}}<br />
<br />
For Authorize.Net, customerId is not required for CCProfileUpdateCustomer. <br />
<br />
CCProfileCreateCustomer and CCProfileUpdateCustomer can also accept a profileDescription, which is a brief description of the customer. It also accepts an email address, which is then stored on the gateway's server.<br />
<br />
=== Creating Payment Profiles===<br />
<br />
{{Template:Payment profiles|{{ANma}}|{{ANpw}}}}<br />
<br />
For Authorize.Net, creating and updating payments accept the following:<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
!Parameters<br />
|-<br />
|firstName<br />
|lastName<br />
|-<br />
|companyName<br />
|address<br />
|-<br />
|city<br />
|state<br />
|-<br />
|zip<br />
|country<br />
|-<br />
|phone<br />
|fax<br />
|}<br />
</center><br />
<br />
ACH payments are added and updated in much the same way as a credit card. Italicized items are optional, and can accept ""; if not needed. ACH payments can use the same CCProfileGetPayment, CCProfileValidatePayment, and CCProfileDeletePayment as above.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePaymentACH</big>||<big>CCProfileUpdatePaymentACH</big><br />
|-<br />
|{{ANma}}||{{ANma}}<br />
|-<br />
|{{ANpw}}||{{ANpw}}<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|accountNumber||paymentProfileId<br />
|-<br />
|routingNumber||''accountNumber''<br />
|-<br />
|bankName||''routingNumber''<br />
|-<br />
|accountType||''bankName''<br />
|-<br />
|accountHolderFirstName||''accountType''<br />
|-<br />
|accountHolderLastName||''accountHolderFirstName''<br />
|-<br />
|||''accountHolderLastName''<br />
|}<br />
<br />
===Creating Shipping Profiles===<br />
<br />
After creating customers and payments, shipping information can also be attached to a customer. Items in bold are required.<br />
<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreateShipping</big><br />
| <big>CCProfileUpdateShipping</big><br />
| <big>CCProfileGetShipping</big><br />
| <big>CCProfileDeleteShipping</big><br />
|-<br />
|'''{{ANma}}'''<br />
|'''{{ANma}}'''<br />
|'''{{ANma}}'''<br />
|'''{{ANma}}'''<br />
|-<br />
<br />
|'''{{ANpw}}'''<br />
|'''{{ANpw}}'''<br />
|'''{{ANpw}}'''<br />
|'''{{ANpw}}'''<br />
|-<br />
|'''customerProfileId'''<br />
|'''customerProfileId'''<br />
|'''customerProfileId'''<br />
|'''customerProfileId'''<br />
|-<br />
| shipFirstName <br />
| shipFirstName <br />
|-<br />
| shipLastName <br />
| shipLastName <br />
|-<br />
| shipCompanyName <br />
| shipCompanyName <br />
|-<br />
| shipAddress <br />
| shipAddress <br />
|-<br />
| shipCity <br />
| shipCity <br />
|-<br />
| shipState<br />
| shipState<br />
|-<br />
| shipZip <br />
| shipZip <br />
|-<br />
| shipCountry <br />
| shipCountry <br />
<br />
|-<br />
| shipPhone<br />
| shipPhone<br />
|-<br />
| shipFax<br />
| shipFax<br />
|}<br />
<br />
'''Returns''': CCCreateShipping returns the shipping ID on success, "ERROR" on failure. CCProfileGetShipping returns the shipping ID on success. Other functions return 1 on success, or "ERROR" if there was a problem.<br />
<br />
=== Running Charges Against Profiles ===<br />
<br />
You can process a payment, authorize a payment, capture an authorized payment, void, and refund transactions. Please note that for unlinked credits with '''CCProfileRefund''', do not pass in an accountNumber or routingNumber.<br />
<br />
If you want to run authorize only transactions, use '''CCProfileProcessPayment''' and add "authMode=AUTH_ONLY" to the list of parameters. To then capture that transaction, run '''CCProfileProcessAuthorizedPayment'''.<br />
<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
| <big>CCProfileProcessAuthorizedPayment</big><br />
| <big> CCProfileRefund </big><br />
| <big> CCProfileVoidPayment</big><br />
|-<br />
|'''{{ANma}}'''||'''{{ANma}}'''||'''{{ANma}}'''||'''{{ANma}}'''<br />
|-<br />
|'''{{ANpw}}'''||'''{{ANpw}}'''||'''{{ANpw}}'''||'''{{ANpw}}'''<br />
|-<br />
|'''customerProfileId'''||'''customerProfileId'''||'''customerProfileId'''||'''customerProfileId'''<br />
|-<br />
|'''paymentProfileId'''||'''paymentProfileId'''||'''paymentProfileId'''||'''paymentProfileId'''<br />
|-<br />
|'''dollarAmount'''||'''previousTransactionId'''||'''previousTransactionId'''||'''previousTransactionId'''<br />
|-<br />
|shippingProfileId||'''dollarAmount''' - pass in ""; if not needed||'''amountToCredit'''<br />
|-<br />
|authMode||shippingProfileId||accountNumber - you can pass in only the last four digits preceded by XXXX<br />
|-<br />
|verificationCode||verificationCode||routingNumber<br />
|-<br />
|invoiceNumber||splitTenderId|||invoiceNumber<br />
|-<br />
|poNumber<br />
|<br />
|poNumber<br />
|-<br />
|chargeDescription<br />
|<br />
|chargeDescription<br />
|-<br />
|isPartialAuthorization<br />
|-<br />
|splitTenderId<br />
|}<br />
<br />
== Getting Response Information and Using Helper Functions ==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/Template:Getting_informationTemplate:Getting information2013-11-05T18:11:07Z<p>Sarah: </p>
<hr />
<div>Plastic includes a number of helper functions that allow users to retrieve data from the gateway or Plastic. <br />
<br />
Simply set a variable or a field to use the calculation. <br />
<br />
* '''CCGetCardIssuer'''(''cardNumber'') - returns the card issuer for a given card number, either: VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB. Returns an error if the card number is from another issuer.<br />
* '''CCGetLast''' (''name'') - returns a value from the most recent transaction response that corresponds with the name parameter.<br />
* '''CCLastAVS'''- returns the gateway's Address Verification System Response for the last payment which was processed. This response is typically a one letter indicator, meaning the following:<br />
{| class="wikitable"<br />
|-<br />
! Code<br />
! Description<br />
! Network<br />
|-<br />
| A<br />
| Street address matches, but 5-digit and 9-digit postal code do not match.<br />
| Standard domestic<br />
|-<br />
| B<br />
| Street address matches, but postal code not verified.<br />
| Standard international<br />
|-<br />
| C<br />
| Street address and postal code do not match.<br />
| Standard international<br />
|-<br />
| D<br />
| Street address and postal code match. Code "M" is equivalent.<br />
| Standard international<br />
|-<br />
| E<br />
| AVS data is invalid or AVS is not allowed for this card type.<br />
| Standard domestic<br />
|-<br />
| G<br />
| Non-U.S. issuing bank does not support AVS.<br />
| Standard international<br />
|-<br />
| I<br />
| Address not verified.<br />
| Standard international<br />
|-<br />
| M<br />
| Street address and postal code match. Code "D" is equivalent.<br />
| Standard international<br />
|-<br />
| N<br />
| Street address and postal code do not match.<br />
| Standard domestic<br />
|-<br />
| P<br />
| Postal code matches, but street address not verified.<br />
| Standard international<br />
|-<br />
| R<br />
| System unavailable.<br />
| Standard domestic<br />
|-<br />
| S<br />
| Bank does not support AVS.<br />
| Standard domestic<br />
|-<br />
| U<br />
| Address information unavailable. Returned if the U.S. bank does not support non-U.S. AVS or if the AVS in a U.S. bank is not functioning properly.<br />
| Standard domestic<br />
|-<br />
| W<br />
| Street address does not match, but 9-digit postal code matches.<br />
| Standard domestic<br />
|-<br />
| X<br />
| Street address and 9-digit postal code match.<br />
| Standard domestic<br />
|-<br />
| Y<br />
| Street address and 5-digit postal code match.<br />
| Standard domestic<br />
|-<br />
| Z<br />
| Street address does not match, but 5-digit postal code matches.<br />
| Standard domestic<br />
|}<br />
* '''CCLastCCV'''- returns the gateway's Card Code Verification Response for the last payment which was processed. This response is typically a one letter indicator, meaning the following:<br />
**M- CVV2/CVC2 Match - Indicates that the card is authentic. Complete the transaction if the authorization request was approved.<br />
**N- CVV2 / CVC2 No Match – May indicate a problem with the card. Contact the cardholder to verify the CVV2 code before completing the transaction, even if the authorization request was approved.<br />
**P- Not Processed - Indicates that the expiration date was not provided with the request, or that the card does not have a valid CVV2 code. If the expiration date was not included with the request, resubmit the request with the expiration date.<br />
**S- Merchant Has Indicated that CVV2 / CVC2 is not present on card - May indicate a problem with the card. Contact the cardholder to verify the CVV2 code before completing the transaction.<br />
**U- Issuer is not certified and/or has not provided visa encryption keys<br />
* '''CCLastChargeResult''' - returns the gateway's result code for the last operation. For Authorize.Net, these are 1- Approved, 2- Declined, or 3- error. PayPal returns 0 on success or a negative value on failure.<br />
* '''CCLastPaymentAuthCode''' - returns the gateway's approval code for the last payment which was processed with CCProcessPayment. <br />
* '''CCLastPaymentTransactionID'''- returns the gateway's transaction ID for the last payment which was processed with CCProcessPayment.<br />
* '''CCLastRawResponse'''- returns the gateway's raw text response for the most recent transaction.<br />
* '''CCValidateCardNumber''' (''cardNumber'') determines if a card number is valid. Returns either a 1 for valid card, or 0 for invalid cards.<br />
* '''CCLastError''' - returns the text of the last error triggered by a plugin function. <br />
* '''CCSetErrorCapture'''- Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call CCSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.<br />
* '''CCLicenseInfo''' - returns information about the license used. <br />
* '''CCRegister''' ( ''licenseKey'', ''registeredTo'') - registers Plastic using the license key and registered to name found in the receipt email. Plastic will run for 2 hours in demo mode before FileMaker Pro will need to be restarted. Returns a 1 on success or a 0 on failure.<br />
* '''CCVersion''' - returns the version of the credit card plugin which is installed.<br />
* '''CCSetTestMode''' - Tells the gateway to flag the account into test mode, which will not let any real charges occur but allow for test transactions. If using our credentials in the demo file with Authorize.Net, these transactions will go to the test server. Returns a 1 on success or ERROR on failure. To send your transactions and account to the test server instead of live with a test flag, use the url parameter instead. See below.<br />
<br />
====Emulator====<br />
<br />
If you would like to use an emulator with Plastic, call the CCSetGateway function with the additional parameter '''url''', whose value would correspond to the emulator's endpoint URL.<br />
<br />
'''Example'''<br/><br />
<pre>Set Variable [$result; Value:CCSetGateway ("Authorize.Net" ; "url=http://YourMerchantParnetURL.com/")]</pre><br />
<br />
The call to CCSetGateway acts as a flag, so all subsequent transactions will point to the alternate URL until otherwise specified or FileMaker is restarted.</div>Sarahhttp://docs.360works.com/index.php/Authorize.NetAuthorize.Net2013-11-05T18:10:16Z<p>Sarah: fixed reference to test server</p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==Authorize.Net==<br />
<br />
Authorize.Net can process a wide variety of transactions, and supports eCheck / ACH payments, profile-based payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
If you do not already have a gateway or merchant account, you can sign up for an Authorize.Net account at the following:<br />
<br />
<center>[https://ems.authorize.net/oap/home.aspx?SalesRepID=98&ResellerID=11334 http://www.authorize.net/images/reseller/oap_sign_up.gif]</center><br />
<br />
You'll need an account using the [https://ems.authorize.net/oap/home.aspx?SalesRepID=98&ResellerID=11334 Authorize.Net Gateway], and use your '''Merchant API Login ID''' and the '''Merchant Transaction Key''' as the first two parameters for every plug-in function call that performs a transaction. The merchant API Login ID is provided in the Merchant Interface from Authorize.Net, and together with the transaction key provides the merchant authentication required for access to the payment gateway. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key''; this is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantAPILoginID;<br />
merchantTransactionKey; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before calling any function in Plastic, the first required step is to set the gateway required.<br />
<br />
Please note that Authorize.Net is the default payment gateway, so there is no need to use CCSetGateway. If you are a merchant who has a card-present account, then you should use the following function first:<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("Authorize.Net"; "cardPresent=true")]</pre><br />
<br />
'''Returns''': 1 if a valid gateway is provided, ERROR otherwise.<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
{{Template:Processing Payments|{{ANma}}|{{ANpw}}}}<br />
<br />
{{Template:AuthorizeNet Optional Parameters}}<br />
<br />
=== Processing ACH Payments ===<br />
<br />
{{Template:Processing ACH payments|{{ANma}}|{{ANpw}}}}<br />
<br />
For Authorize.NET payments, you MUST also pass in an achType as a key value parameter. You don't necessarily need to pass bankName, accountType, accountHolderFirstName, and accountHolderLastName. If you do not have that information, you can pass in a blank value with "";<br />
<br />
If taking a Account Receivable Transaction (ARC) or Back Office Conversion (BOC) payment, you must also pass in a check number. If not, simply type ""; where that checkNumber field would be. <br />
{{Template:AuthorizeNet Optional Parameters}}<br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|{{ANma}}|{{ANpw}}}}<br />
<br />
Set Variable [$result Value: <br />
CCProcessAuthorizedPayment(<br />
{{ANma}};<br />
{{ANpw}};<br />
previousTransactionId;<br />
dollarAmount)]<br />
<br />
<br />
The dollarAmount is not required to process the authorized payment. CCProcessAuthorizedPayment accepts the same optional parameters as CCProcessPayment.<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
Set Variable [$result; Value:<br />
CCProcessPayment(<br />
{{ANma}};<br />
{{ANpw}};<br />
chargeAmount;<br />
"";<br />
"";<br />
"track1=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
<br />
=== Partial Transactions === <br />
<br />
====Using "isPartailAuthroization=true" and splitTenderId====<br />
<br />
When using CCProcessPayment, specifying the additional parameter "authMode=AUTH_ONLY" will perform an authorization as opposed to a sale transaction. Specifying the "isPartialAuthorization=true" parameter will tell the gateway to allow for partial authorizations of pre-paid credit cards, gift cards and debit cards. Specifying the splitTenderId parameter tells the gateway that the amount authorized for the current transaction will be applied toward the remaining balance of a previous transaction identified by the split tender ID.<br />
<br />
When using CCProcessAuthorizedPayment, users can also pass in the splitTenderId instead of the previous transaction ID. This will capture the authorized amount from a previous transaction.<br />
<br />
====Charging the Outstanding Balance====<br />
<br />
After specifying a partial authorization, you can request the remaining balance and the requested amount by using CCPartialGetRemainingBalance and CCPartialGetRequestedAmount. Both return the dollar amounts, and do not require any additional parameters. You can also retrieve the splitTenderId with CCLastSplitTenderId.<br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|{{ANma}}|{{ANpw}}}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|{{ANma}}|{{ANpw}}}}<br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with Authorize.Net, pass in the blank transaction ID. It will be a little different based on whether it was a swiped or a typed card:<br />
<br />
{|<br />
|-<br />
|''Card Not Present Unlinked Refund''<br />
|''Card Present Unlinked Refund''<br />
|-<br />
||<br />
Set Variable [$result Value:<br />
CCRefund(<br />
{{ANma}};<br />
{{ANpw}};<br />
"";<br />
cardNumber;<br />
chargeAmount;<br />
"expirationDate=12/13")]<br />
||<br />
Set Variable [$result Value:<br />
CCRefund(<br />
{{ANma}};<br />
{{ANpw}};<br />
"";<br />
"";<br />
chargeAmount;<br />
"track1=";<br />
"track2=")]<br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
Authorize.Net supports all five subscription functions. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. <br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use '''CCCreateSubscriptionACH.''' Italicized items are optional.<br />
<br />
Valid pay periods include days or months. Frequency indicates how often in that period. For example, a biweekly subscription would have a pay period of weekly and a frequency of 2. <br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|{{ANma}}||{{ANma}}<br />
|-<br />
|{{ANpw}}||{{ANpw}}<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|''subscriptionName''||''bankName''<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||accountHolderFirstName<br />
|-<br />
|payPeriod||accountHolderLastName<br />
|-<br />
|frequncy||''subscriptionName''<br />
|-<br />
|||numberOfInstallments<br />
|-<br />
| || startDate<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || frequency<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''. The optional parameters can be set to "" if you do not need to modify them. The last two, marked with ""; are payPeriod and frequency, which cannot be modified. <br />
<br />
The trialOccurrences parameter can only be updated if the trial period has not begun or is in progress.<br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|{{ANma}}||{{ANma}}<br />
|-<br />
|{{ANpw}}||{{ANpw}}<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|''dollarAmount''||''dollarAmount''<br />
|-<br />
|''cardNumber''||''accountNumber''<br />
|-<br />
|''expirationDate''||''abaRoutingNumber''<br />
|-<br />
|''subscriptionName''||''bankName''<br />
|-<br />
|''numberOfInstallments''||''accountType''<br />
|-<br />
|''startDate''||''accountHolderFirstName''<br />
|-<br />
|"";||''accountHolderLastName''<br />
|-<br />
|"";||''subscriptionName''<br />
|-<br />
|||''numberOfInstallments''<br />
|-<br />
| || ''startDate''<br />
|-<br />
| ||"";<br />
|-<br />
| || "";<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying subscriptions:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|trialOccurrences <br />
|The number of installments includes any trial occurrences. If you specify a trial occurrence, you must also specify a trialAmount.<br />
|-<br />
|trialAmount <br />
|If you specify a trial amount, you must also specify the trialOccurrences.<br />
|-<br />
|verificationCode <br />
|the numeric verification code on the credit card. This is also known as Card Security Code (CSC), Card Verification Value (CVV), Card Verification Value Code (CVVC), Card Verification Code (CVC) or Verification Code (V-Code/V Code)<br />
|-<br />
|invoiceNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|companyName <br />
|the billing company name<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|-<br />
|shipAddress <br />
|the shipping street address<br />
|-<br />
|shipCity <br />
|the shipping address city<br />
|-<br />
|shipCompanyName <br />
|the shipping recipient's company name<br />
|-<br />
|shipCountry <br />
|the shipping address country<br />
|-<br />
|shipFirstName <br />
|the shipping recipient's first name<br />
|-<br />
|shipLastName <br />
|the shipping recipient's last name<br />
|-<br />
|shipState <br />
|the shipping address state<br />
|-<br />
|shipZip <br />
|the shipping address zip<br />
|}<br />
</center><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|merchantAccountName<br />
|-<br />
|transactionKey<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
== Payment Profiles ==<br />
<br />
{{Template:Customer profiles|{{ANma}}|{{ANpw}}}}<br />
{{Template:Profiles}}<br />
<br />
For Authorize.Net, customerId is not required for CCProfileUpdateCustomer. <br />
<br />
CCProfileCreateCustomer and CCProfileUpdateCustomer can also accept a profileDescription, which is a brief description of the customer. It also accepts an email address, which is then stored on the gateway's server.<br />
<br />
=== Creating Payment Profiles===<br />
<br />
{{Template:Payment profiles|{{ANma}}|{{ANpw}}}}<br />
<br />
For Authorize.Net, creating and updating payments accept the following:<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
!Parameters<br />
|-<br />
|firstName<br />
|lastName<br />
|-<br />
|companyName<br />
|address<br />
|-<br />
|city<br />
|state<br />
|-<br />
|zip<br />
|country<br />
|-<br />
|phone<br />
|fax<br />
|}<br />
</center><br />
<br />
ACH payments are added and updated in much the same way as a credit card. Italicized items are optional, and can accept ""; if not needed. ACH payments can use the same CCProfileGetPayment, CCProfileValidatePayment, and CCProfileDeletePayment as above.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePaymentACH</big>||<big>CCProfileUpdatePaymentACH</big><br />
|-<br />
|{{ANma}}||{{ANma}}<br />
|-<br />
|{{ANpw}}||{{ANpw}}<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|accountNumber||paymentProfileId<br />
|-<br />
|routingNumber||''accountNumber''<br />
|-<br />
|bankName||''routingNumber''<br />
|-<br />
|accountType||''bankName''<br />
|-<br />
|accountHolderFirstName||''accountType''<br />
|-<br />
|accountHolderLastName||''accountHolderFirstName''<br />
|-<br />
|||''accountHolderLastName''<br />
|}<br />
<br />
===Creating Shipping Profiles===<br />
<br />
After creating customers and payments, shipping information can also be attached to a customer. Items in bold are required.<br />
<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreateShipping</big><br />
| <big>CCProfileUpdateShipping</big><br />
| <big>CCProfileGetShipping</big><br />
| <big>CCProfileDeleteShipping</big><br />
|-<br />
|'''{{ANma}}'''<br />
|'''{{ANma}}'''<br />
|'''{{ANma}}'''<br />
|'''{{ANma}}'''<br />
|-<br />
<br />
|'''{{ANpw}}'''<br />
|'''{{ANpw}}'''<br />
|'''{{ANpw}}'''<br />
|'''{{ANpw}}'''<br />
|-<br />
|'''customerProfileId'''<br />
|'''customerProfileId'''<br />
|'''customerProfileId'''<br />
|'''customerProfileId'''<br />
|-<br />
| shipFirstName <br />
| shipFirstName <br />
|-<br />
| shipLastName <br />
| shipLastName <br />
|-<br />
| shipCompanyName <br />
| shipCompanyName <br />
|-<br />
| shipAddress <br />
| shipAddress <br />
|-<br />
| shipCity <br />
| shipCity <br />
|-<br />
| shipState<br />
| shipState<br />
|-<br />
| shipZip <br />
| shipZip <br />
|-<br />
| shipCountry <br />
| shipCountry <br />
<br />
|-<br />
| shipPhone<br />
| shipPhone<br />
|-<br />
| shipFax<br />
| shipFax<br />
|}<br />
<br />
'''Returns''': CCCreateShipping returns the shipping ID on success, "ERROR" on failure. CCProfileGetShipping returns the shipping ID on success. Other functions return 1 on success, or "ERROR" if there was a problem.<br />
<br />
=== Running Charges Against Profiles ===<br />
<br />
You can process a payment, authorize a payment, capture an authorized payment, void, and refund transactions. Please note that for unlinked credits with '''CCProfileRefund''', do not pass in an accountNumber or routingNumber.<br />
<br />
If you want to run authorize only transactions, use '''CCProfileProcessPayment''' and add "authMode=AUTH_ONLY" to the list of parameters. To then capture that transaction, run '''CCProfileProcessAuthorizedPayment'''.<br />
<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
| <big>CCProfileProcessAuthorizedPayment</big><br />
| <big> CCProfileRefund </big><br />
| <big> CCProfileVoidPayment</big><br />
|-<br />
|'''{{ANma}}'''||'''{{ANma}}'''||'''{{ANma}}'''||'''{{ANma}}'''<br />
|-<br />
|'''{{ANpw}}'''||'''{{ANpw}}'''||'''{{ANpw}}'''||'''{{ANpw}}'''<br />
|-<br />
|'''customerProfileId'''||'''customerProfileId'''||'''customerProfileId'''||'''customerProfileId'''<br />
|-<br />
|'''paymentProfileId'''||'''paymentProfileId'''||'''paymentProfileId'''||'''paymentProfileId'''<br />
|-<br />
|'''dollarAmount'''||'''previousTransactionId'''||'''previousTransactionId'''||'''previousTransactionId'''<br />
|-<br />
|shippingProfileId||'''dollarAmount''' - pass in ""; if not needed||'''amountToCredit'''<br />
|-<br />
|authMode||shippingProfileId||accountNumber - you can pass in only the last four digits preceded by XXXX<br />
|-<br />
|verificationCode||verificationCode||routingNumber<br />
|-<br />
|invoiceNumber||splitTenderId|||invoiceNumber<br />
|-<br />
|poNumber<br />
|<br />
|poNumber<br />
|-<br />
|chargeDescription<br />
|<br />
|chargeDescription<br />
|-<br />
|isPartialAuthorization<br />
|-<br />
|splitTenderId<br />
|}<br />
<br />
== Getting information ==<br />
<br />
{{Template:Getting information}}<br />
<br />
If you have your own test account from Authorize.Net and would like to use the test servers provided by Authorize.Net, use one of the following:<br />
<br />
'''Standard Transactions''':<br />
<br />
Set Variable [$result; Value: CCSetGateway ("Authorize.Net" ; "url=https://test.authorize.net/gateway/transact.dll")]<br />
<br />
'''Profile or Subscription Transactions''': (Customer Information Manager or Automated Recurring Billing)<br />
<br />
Set Variable [$result; Value: CCSetGateway ("Authorize.Net" ; "url=https://apitest.authorize.net/soap/v1/Service.asmx")]<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/USA_ePAYUSA ePAY2013-11-04T20:07:43Z<p>Sarah: </p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==USA ePay==<br />
<br />
USA ePay can process a wide variety of transactions, including eCheck / ACH payments, profile-based payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [http://www.usaepay.com/resellerlist USA ePay Gateway], and use your '''source key''' and the '''PIN''' as the first two parameters for every plug-in function call that performs a transaction. You can log into your account at USA ePay and generate the PIN there. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of source key and PIN. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
sourceKey;<br />
pin; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("USA ePay")]<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
If running card present charges, you should also set cardPresent to true when setting the gateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("USA ePay"; "cardPresent=true")<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
{{Template:Processing Payments|merchantId|pin|}}<br />
<br />
{{Template:USA Optional Parameters}}<br />
<br />
=== Processing ACH payments ===<br />
<br />
Plastic 2 now supports payments via direct bank transfers and eChecks, via ACH payments. To take a payment via eCheck, use the '''CCProcessPaymentACH''' function after calling the gateway. <br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPaymentACH ( <br />
sourceKey; <br />
pin; <br />
dollarAmount;<br />
accountNumber; <br />
routingNumber;<br />
""; <br />
accountType; <br />
accountHolderFirstName; <br />
accountHolderLastName;<br />
checkNumber;<br />
"achType=ARC";<br />
"driversLicenseNumber=2345431";<br />
"driversLicenseState=GA")]</pre><br />
<br />
You must pass in the ACH Type and driver's license information. Do so by adding the extra parameters as key=value pairs. The blank placeholder is marked with ""; - normally you would use this parameter for a bank name, but that is not supported in USA ePay transactions. <br />
<br />
If taking a Account Receivable Transaction (ARC) or Back Office Conversion (BOC) payment, you must also pass in a check number. If not, simply type ""; where that checkNumber field would be.<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|invoiceNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|poNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|currency<br />
|the currency used in the transaction<br />
|-<br />
|orderId <br />
|an arbitrary order number for your records<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|companyName<br />
|the billing company name<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|address2<br />
|the second line of the billing address<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|-<br />
|shipFirstName <br />
|the shipping recipient's first name<br />
|-<br />
|shipLastName <br />
|the shipping recipient's last name<br />
|-<br />
|shipEmail <br />
|the shipping recipient's email<br />
|-<br />
|shipPhone <br />
|the shipping recipient's phone<br />
|-<br />
|shipFax <br />
|the shipping recipient's fax number<br />
|-<br />
|shipCompanyName<br />
|the shipping company name<br />
|-<br />
|shipAddress <br />
|the shipping street address<br />
|-<br />
|shipAddress2 <br />
|the shipping address second line<br />
|-<br />
|shipCity <br />
|the shipping address city<br />
|-<br />
|shipState <br />
|the shipping address state<br />
|-<br />
|shipZip <br />
|the shipping address zip<br />
|-<br />
|shipCountry<br />
|the shipping address country<br />
|}<br />
</center><br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|sourceKey|pin}}<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessAuthorizedPayment(<br />
sourceKey, <br />
pin;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre><br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
sourceKey;<br />
pin;<br />
chargeAmount;<br />
"";<br />
"";<br />
"track1=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
</pre><br />
<br />
Pass in either track1 or track2.<br />
<br />
=== Partial Transactions === <br />
<br />
When using CCProcessPayment, specifying the additional parameter "authMode=AUTH_ONLY" will perform an authorization as opposed to a sale transaction. Specifying the "isPartialAuthorization=true" parameter will tell the gateway to allow for partial authorizations of pre-paid credit cards, gift cards and debit cards. <br />
<br />
After specifying a partial authorization, you can request the remaining balance and the requested amount by using CCPartialGetRemainingBalance and CCPartialGetRequestedAmount. Both return the dollar amounts, and do not require any additional parameters.<br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|sourceKey|pin}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|sourceKey|pin}}<br />
<br />
If you do not pass a dollar amount, it will refund the whole amount of the transaction. <br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction. It will be a little different based on whether the refund is from an ACH or credit card:<br />
<br />
{|<br />
|-<br />
|''Credit Card Unlinked Refund''<br />
|''ACH Unlinked Refund''<br />
|-<br />
| <pre>Set Variable [$result Value:<br />
CCRefund(<br />
sourceKey,<br />
pin;<br />
"";<br />
cardNumber;<br />
chargeAmount;<br />
"expirationDate=12/13")]<br />
<br />
</pre><br />
|| <pre>Set Variable [$result Value:<br />
CCRefund(<br />
sourceKey,<br />
pin;<br />
"";<br />
accountNumber;<br />
chargeAmount;<br />
"routingNumber=";<br />
"accountType=";<br />
"achType=";<br />
"driversLicenseNumber=";<br />
"driversLicenseState=";<br />
"checkNumber=")]<br />
</pre><br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
USA ePay supports all five subscription functions. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. <br />
<br />
Valid pay periods include daily, weekly, biweekly, monthly, bimonthly, quarterly, biannually, and annually. The number of installments specify how many transactions to run. A six month subscription would specify a payPeriod of monthly, and 6 installments.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use '''CCCreateSubscriptionACH.''' Italicized items are optional.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||accountHolderFirstName<br />
|-<br />
|payPeriod||accountHolderLastName<br />
|-<br />
|"";||"";<br />
|-<br />
|||numberOfInstallments<br />
|-<br />
| || startDate<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
'''Returns''': the subscription ID on success, "ERROR" on failure. <br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''. The optional parameters can be set to "" if you do not need to modify them. The last two, marked with ""; are payPeriod and frequency, which cannot be modified. <br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big>|| <big>CCModifySubscriptionACH</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|''dollarAmount''||''dollarAmount''<br />
|-<br />
|''cardNumber''||''accountNumber''<br />
|-<br />
|''expirationDate''||''abaRoutingNumber''<br />
|-<br />
|"";||"";<br />
|-<br />
|''numberOfInstallments''||''accountType''<br />
|-<br />
|''startDate''||''accountHolderFirstName''<br />
|-<br />
|payPeriod||''accountHolderLastName''<br />
|-<br />
|"";||"";<br />
|-<br />
|||''numberOfInstallments''<br />
|-<br />
| || ''startDate''<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying credit card subscriptions:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|maxFailures<br />
|the maximum amount of times that the charge should try<br />
|-<br />
|poNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|currency <br />
|the charge currency<br />
|-<br />
|orderId<br />
|an arbitrary order number for your records<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|companyName<br />
|the card holder's company name<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|address2<br />
|the billing address second line<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|}<br />
</center><br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying ACH subscriptions:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|achType<br />
|the classification of ACH transaction type<br />
|-<br />
|driversLicenseNumber<br />
|the account holder's driver's license number<br />
|-<br />
|driversLicenseState<br />
|the account holder's driver's license state<br />
|-<br />
|maxFailures<br />
|the maximum amount of times that the charge should try<br />
|-<br />
|poNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|currency <br />
|the charge currency<br />
|-<br />
|orderId<br />
|an arbitrary order number for your records<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|companyName<br />
|the card holder's company name<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|address2<br />
|the billing address second line<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|}<br />
</center><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|sourceKey<br />
|-<br />
|pin<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
== Payment Profiles ==<br />
<br />
{{Template:Customer profiles|sourceKey|pin}}<br />
<br />
{{Template:Profiles}}<br />
<br />
You don't necessarily need to pass in a customer ID for creating or updating a customer profile. <br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying customers:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
|-<br />
|profileDescription<br />
|-<br />
|firstName<br />
|-<br />
|lastName<br />
|-<br />
|email<br />
|-<br />
|phone<br />
|-<br />
|fax<br />
|-<br />
|companyName<br />
|-<br />
|address<br />
|-<br />
|address2<br />
|-<br />
|city<br />
|-<br />
|state<br />
|-<br />
|zip<br />
|-<br />
|country<br />
|}<br />
</center><br />
<br />
=== Creating Payment Profiles===<br />
<br />
Payment profiles allow you to save payment information straight to the gateway for future use. To create a payment profile, call either '''CCProfileCreatePayment''' or '''CCProfileCreatePaymentACH''', depending on whether the payment profile is a credit card or ACH. Credit cards are created with '''CCProfileCreatePayment''' and updated with '''CCProfileUpdatePayment'''. Italicized items are optional, and can accept ""; if not needed.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePayment</big><br />
| <big>CCProfileUpdatePayment</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|cardNumber||paymentProfileId<br />
|-<br />
|expirationDate||''cardNumber''<br />
|-<br />
|||''expirationDate''<br />
|}<br />
<br />
'''Returns''': Creating a payment will return the ID of the profile created, "ERROR" on failure. Updating will return 1 on success, "ERROR" on failure.<br />
<br />
Optional parameters: profileDescription, verificationCode.<br />
<br />
After creation, payments can be retrieved with '''CCProfileGetPayment''' Payments can be deleted with '''CCProfileDeletePayment'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileGetPayment</big><br />
| <big>CCProfileDeletePayment</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|paymentProfileId||paymentProfileId<br />
|}<br />
<br />
'''Returns''': Getting a payment will return the ID of the profile requested, "ERROR" on failure. Deletions will return 1 on success, "ERROR" on failure.<br />
<br />
ACH payments are added and updated in much the same way as a credit card. Italicized items are optional, and can accept ""; if not needed. ACH payments can use the same CCProfileGetPayment, CCProfileValidatePayment, and CCProfileDeletePayment as above.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePaymentACH</big>||<big>CCProfileUpdatePaymentACH</big><br />
|-<br />
|sourceKey||sourceKey<br />
|-<br />
|pin||pin<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|accountNumber||paymentProfileId<br />
|-<br />
|routingNumber||''accountNumber''<br />
|-<br />
|"";||''routingNumber''<br />
|-<br />
|accountType||"";<br />
|-<br />
|"";||''accountType''<br />
|-<br />
|"";||"";<br />
|-<br />
|||"";<br />
|}<br />
<br />
'''Returns''': Creating a payment will return the ID of the profile created, "ERROR" on failure. Updating will return 1 on success, "ERROR" on failure.<br />
<br />
Optional parameters: achType, driversLicenseNumber, driversLicenseState.<br />
<br />
=== Running Charges Against Profiles ===<br />
<br />
You can process a payment and refund transactions using the saved payment data. Please note you'll need to mark whether the original payment method was an ACH or credit card using the key=value pair.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
| <big> CCProfileRefund </big><br />
|-<br />
|'''sourceKey'''||'''sourceKey'''<br />
|-<br />
|'''pin'''||'''pin'''<br />
|-<br />
|'''customerProfileId'''||'''customerProfileId'''<br />
|-<br />
|'''paymentProfileId'''||'''paymentProfileId'''<br />
|-<br />
|'''dollarAmount'''||'''previousTransactionId'''<br />
|-<br />
|"methodOfPayment=CC"||'''amountToCredit'''<br />
|-<br />
|||"";<br />
|-<br />
|||"methodOfPayment=ACH"<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters for CCProfileProcessPayment:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
!Parameters<br />
|-<br />
|verificationCode<br />
|invoiceNumber<br />
|-<br />
|poNumber<br />
|chargeDescription<br />
|-<br />
|customerId<br />
|currency<br />
|-<br />
|orderId<br />
|}<br />
<br />
</center><br />
<br />
'''Returns''': Payments return a transaction ID from the payment gateway service if the transaction is successful, or "ERROR" if there was a problem. Refunds will return 1 on success, or "ERROR" if there was a problem.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/TransFirstTransFirst2013-11-04T20:04:27Z<p>Sarah: </p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==TransFirst==<br />
<br />
TransFirst can process a wide variety of transactions, including eCheck / ACH payments, profile-based payments, and subscriptions. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [http://www.transfirst.com/merchant-accounts TransFirst Gateway], and use your '''merchant ID''' and the '''hosted key''' as the first two parameters for every plug-in function call that performs a transaction. You'll receive these from TransFirst once you obtain a merchant account. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of merchant ID and hosted key. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantId; <br />
hostedKey; ; ...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("TransFirst")]<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
If running card present charges, you should also set cardPresent to true when setting the gateway.<br />
<br />
Set Variable [$gateway; Value:CCSetGateway("TransFirst"; "cardPresent=true")==Processing Payments==<br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
{{Template:Processing Payments|merchantId|hostedKey}}<br />
<br />
{{Template:TransFirst Optional Parameters}}<br />
<br />
=== Processing ACH Payments ===<br />
<br />
Plastic 2 now supports payments via direct bank transfers and eChecks, via ACH payments. To take a payment via <br />
eCheck, use the CCProcessPaymentACH function after calling the gateway.<br />
<br />
<pre><br />
Set Variable [$result; Value:<br />
CCProcessPaymentACH ( <br />
merchantId; <br />
hostedKey; <br />
dollarAmount;<br />
accountNumber; <br />
routingNumber;<br />
""; <br />
accountType; <br />
accountHolderFirstName; <br />
accountHolderLastName;<br />
"";<br />
"checkType=" )]</pre><br />
<br />
Notice the blanks-- normally you should pass in a bank name and a check number in those positions, but TransFirst does not require that information. It does, however, require a check type, so use the key=value syntax to pass in that required parameter. <br />
<br />
{{Template:TransFirst Optional Parameters}}<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
merchantId;<br />
hostedKey;<br />
chargeAmount;<br />
"";<br />
"";<br />
"swipe=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
</pre><br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|merchantId|hostedKey}}<br />
<br />
With TransFirst, you should also pass in the method of payment used: ACH or CC with "methodOfPayment="<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|merchantId|hostedKey}}<br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with TransFirst, pass in the blank transaction ID. It will be a little different based on whether it was a ACH or credit card:<br />
<br />
{|<br />
|-<br />
|''Credit Card Unlinked Refund''<br />
|''ACH Unlinked Refund''<br />
|-<br />
| <pre>Set Variable $result Value:<br />
CCRefund(<br />
merchantId,<br />
hostedKey;<br />
"";<br />
cardNumber;<br />
chargeAmount;<br />
"expirationDate=12/13")<br />
<br />
</pre><br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
merchantId,<br />
hostedKey;<br />
"";<br />
accountNumber;<br />
chargeAmount;<br />
"routingNumber="<br />
"checkType=")<br />
</pre><br />
|}<br />
<br />
<br />
CCRefund also allows you to submit an optional orderId. With a credit card refund, you can also pass in the verificationCode, poNumber, chargeDescription, firstName, lastName, address, and zip.<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
TransFirst supports all every function but deletions. To cancel a subscription, modify its properties instead. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. <br />
<br />
Valid pay periods include monthly, quarterly, yearly, weekly, bi-weekly, every4weeks, and every8weeks. The number of installments specify how many transactions to run. A six month subscription would specify a payPeriod of monthly, and 6 installments.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use '''CCCreateSubscriptionACH.''' Italicized items are optional.<br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|merchantId||merchantId<br />
|-<br />
|hostedKey||hostedKey<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|"";||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||accountHolderFirstName<br />
|-<br />
|payPeriod||accountHolderLastName<br />
|-<br />
|"";||"";<br />
|-<br />
|||numberOfInstallments<br />
|-<br />
| || startDate<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
'''Returns''': the ID of the subscription created, "ERROR" on failure. <br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''. The optional parameters can be set to "" if you do not need to modify them. The last two, marked with ""; are payPeriod and frequency, which cannot be modified. <br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big>|| <big>CCModifySubscriptionACH</big><br />
|-<br />
|merchantId||merchantId<br />
|-<br />
|hostedKey||hostedKey<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|''dollarAmount''||''dollarAmount''<br />
|-<br />
|''cardNumber''||''accountNumber''<br />
|-<br />
|''expirationDate''||''abaRoutingNumber''<br />
|-<br />
|''subscriptionName''||''bankName''<br />
|-<br />
|''numberOfInstallments''||''accountType''<br />
|-<br />
|''startDate''||''accountHolderFirstName''<br />
|-<br />
|payPeriod||''accountHolderLastName''<br />
|-<br />
|"";||"";<br />
|-<br />
|||''numberOfInstallments''<br />
|-<br />
| || ''startDate''<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
<center><big>Click Expand to see the list of optional parameters for creating and modifying subscriptions:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
|-<br />
|firstName ||lastName<br />
|-<br />
|address ||zip<br />
|}<br />
</center><br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
==Payment Profiles==<br />
<br />
=== Creating Payment Profiles===<br />
<br />
Payment profiles allow you to save payment information straight to the gateway for future use. To create a payment profile, call either '''CCProfileCreatePayment''' or '''CCProfileCreatePaymentACH''', depending on whether the payment profile is a credit card or ACH. Credit cards are created with '''CCProfileCreatePayment''' and updated with '''CCProfileUpdatePayment'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePayment</big><br />
| <big>CCProfileUpdatePayment</big><br />
|-<br />
|merchantId<br />
|merchantId<br />
|-<br />
|hostedKey<br />
|hostedKey<br />
|-<br />
|customerProfileId<br />
|customerProfileId<br />
|-<br />
|cardNumber<br />
|paymentProfileId<br />
|-<br />
|expirationDate<br />
|''cardNumber''<br />
|-<br />
|<br />
|''expirationDate''<br />
|}<br />
<br />
'''Returns''': Creating a payment will return the ID of the profile created, "ERROR" on failure. Updating will return 1 on success, "ERROR" on failure.<br />
<br />
After creation, payments can be retrieved with '''CCProfileGetPayment'''. Payments can be deleted with '''CCProfileDeletePayment'''.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileGetPayment</big><br />
| <big>CCProfileDeletePayment</big><br />
|-<br />
|merchantId<br />
|merchantId<br />
|-<br />
|hostedKey<br />
|hostedKey<br />
<br />
|-<br />
|customerProfileId<br />
|customerProfileId<br />
<br />
|-<br />
|paymentProfileId<br />
|paymentProfileId<br />
|}<br />
<br />
'''Returns''': Getting a payment will return the ID of the profile requested, "ERROR" on failure. Deletions will return 1 on success, "ERROR" on failure.<br />
<br />
Card number and expiration dates are not required when updating the payment.<br />
<br />
{{Template:Profiles}}<br />
<br />
ACH payments are added and updated in much the same way as a credit card. Italicized items are optional, and can accept ""; if not needed. ACH payments can use the same CCProfileGetPayment and CCProfileDeletePayment as above.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileCreatePaymentACH</big>||<big>CCProfileUpdatePaymentACH</big><br />
|-<br />
|merchantId||merchantId<br />
|-<br />
|hostedKey||hostedKey<br />
|-<br />
|customerProfileId||customerProfileId<br />
|-<br />
|accountNumber||paymentProfileId<br />
|-<br />
|routingNumber||''accountNumber''<br />
|-<br />
|"";||''routingNumber''<br />
|-<br />
|''accountType''||''bankName''<br />
|-<br />
|''accountHolderFirstName''||''accountType''<br />
|-<br />
|''accountHolderLastName''||''accountHolderFirstName''<br />
|-<br />
|||''accountHolderLastName''<br />
|}<br />
<br />
For TransFirst, creating and updating payments accept the following:<br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
!Parameters<br />
|-<br />
|poNumber<br />
|chargeDescription<br />
|-<br />
|firstName<br />
|lastName<br />
|-<br />
|companyName<br />
|address<br />
|-<br />
|address<br />
|zip<br />
|-<br />
|orderId<br />
|}<br />
</center><br />
<br />
'''Returns''': Creating a payment will return the ID of the profile created, "ERROR" on failure. Updating will return 1 on success, "ERROR" on failure.<br />
<br />
=== Running Charges Against Profiles ===<br />
<br />
To process a payment after it has been saved, use CCProfileProcessPayment.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
|-<br />
|'''merchantId'''<br />
|-<br />
|'''hostedKey'''<br />
|-<br />
|'''customerProfileId'''<br />
|-<br />
|'''paymentProfileId'''<br />
|-<br />
|'''dollarAmount'''<br />
|-<br />
|"methodOfPayment="<br />
|-<br />
|"customerId="<br />
|-<br />
|"verificationCode="<br />
|}<br />
<br />
'''Returns''': a transaction ID from the payment gateway service if the transaction is successful, or "ERROR" if there was a problem.<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}</div>Sarahhttp://docs.360works.com/index.php/Payflow_ProPayflow Pro2013-11-04T20:01:22Z<p>Sarah: </p>
<hr />
<div>==Working with Plug-ins==<br />
<br />
Plastic 2 is a plug-in for FileMaker Pro and FileMaker Server that processes secure payments within FileMaker.<br />
<br />
{{Template:Plugin Basics}}<br />
<br />
==PayPal Payflow Pro==<br />
<br />
Payflow Pro can process a wide variety of transactions, including eCheck / ACH payments, card present swipes, and more. Payflow Pro can also set up a subscription, which automatically charges a credit card or debits a bank account on a set basis. For detailed examples of each of these transactions, check the demo file included as a download with Plastic 2. These scripts are ready for insertion into your own solution!<br />
<br />
=== Getting an account ===<br />
<br />
You'll need an account using the [https://registration.paypal.com/welcomePage.do?producttype=C2&country=US&mode=try|PayPal PayFlow Pro Gateway], and use your '''merchant login''' and the '''password''' as the first two parameters for every plug-in function call that performs a transaction. In the function signature template, you may see the terms ''merchant account name'' and ''transaction key'' instead of merchant login and password. This is due to the fact that Plastic 2 supports many gateways that use different definitions of log-in credentials. <br />
<br />
If you can log on to [http://manager.paypal.com manager.paypal.com] with your credentials, you'll be able to use the Plastic plug-in. If you received an account directly from PayPal, you can use "PayPal" as the partner at the log-in screen. <br />
<br />
Set Variable [ $result; Value:<br />
CCProcessPayment (<br />
merchantLogin;<br />
password;<br />
...) ]<br />
<br />
=== Setting the Gateway ===<br />
<br />
Before processing any payments, you need to tell Plastic which gateway you are using. This is done by calling CCSetGateway. <br />
<br />
Set Variable [$gateway; Value:CCSetGateway("Payflow Pro")<br />
<br />
'''Returns''': 1 if a valid gateway is provided, "ERROR" on failure.<br />
<br />
If running card present charges, you should also set cardPresent to true when setting the gateway.<br />
<br />
<pre>Set Variable [$gateway; Value:CCSetGateway("Payflow Pro"; "cardPresent=true")]</pre><br />
<br />
==Processing Payments==<br />
<br />
===Basic Credit Card Charge===<br />
<br />
This simple example will run a single charge and requires you to input a card number and expiration date. To prevent this information from being saved in your database and to simplify PCI compliance, jump to the [[#Payment Profiles]] section.<br />
<br />
Before running any charges or transactions, first evaluate if you must set up the user and partner. User is required if you have set up an additional user (besides the default merchant log in ID) for your PayFlow Pro account and you wish to run a transaction as that user. Partner is required if your Payflow Pro account was purchased from a reseller. Pass the ID provided by the reseller who registered you for the Payflow Pro service. '''If you meet these conditions, pass these values in every time you use payment processing functions'''.<br />
<br />
"user=account1"<br />
"partner=1234190"<br />
<br />
{{Template:Processing Payments|merchantLogin|password}}<br />
{{Template:PayFlow Pro Optional Parameters}}<br />
<br />
=== Processing ACH Payments ===<br />
<br />
{{Template:Processing ACH payments|merchantLogin|password}}<br />
<br />
For Payflow Pro, bankName is not an accepted parameter. Therefore, you must pass a blank value instead:<br />
<br />
<pre>Set Variable [$result Value: <br />
CCProcessPaymentACH(<br />
merchantLogin, <br />
password;<br />
dollarAmount;<br />
accountNumber;<br />
routingNumber;<br />
"";<br />
accountType;<br />
accountHolderFirstName;<br />
accountHolderLastName;<br />
checkNumber;<br />
"achType=ARC")<br />
</pre><br />
<br />
If taking a Account Receivable Transaction (ARC), Back Office Conversion (BOC), or Point of Purchase (POP) payment, you must also pass in a check number. If not, simply type ""; where that checkNumber field would be. <br />
<br />
<center><big>Click Expand to see the list of optional parameters:</big><br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! Parameter<br />
! Description<br />
|-<br />
|invoiceNumber <br />
|an arbitrary invoice number for your records<br />
|-<br />
|poNumber <br />
|an arbitrary PO number for your records<br />
|-<br />
|chargeDescription <br />
|brief description of the charges<br />
|-<br />
|customerId <br />
|an arbitrary customer ID for your records<br />
|-<br />
|companyName <br />
|the billing company name<br />
|-<br />
|firstName <br />
|First (given) name of the credit card holder<br />
|-<br />
|lastName <br />
|Last (surname) of the credit card holder<br />
|-<br />
|email <br />
|the card holder's email address<br />
|-<br />
|fax <br />
|the card holder's fax number<br />
|-<br />
|phone<br />
|the card holder's phone number<br />
|-<br />
|address<br />
|the billing address<br />
|-<br />
|city <br />
|the billing address city<br />
|-<br />
|state <br />
|the billing address state<br />
|-<br />
|zip <br />
|the billing address zip<br />
|-<br />
|country <br />
|billing address country<br />
|-<br />
|shipAddress <br />
|the shipping street address<br />
|-<br />
|shipCity <br />
|the shipping address city<br />
|-<br />
|shipCountry <br />
|the shipping address country<br />
|-<br />
|shipFirstName <br />
|the shipping recipient's first name<br />
|-<br />
|shipLastName <br />
|the shipping recipient's last name<br />
|-<br />
|shipState <br />
|the shipping address state<br />
|-<br />
|shipZip <br />
|the shipping address zip<br />
|-<br />
|shipEmail<br />
|the shipping recipient's email<br />
|-<br />
|shipPhone<br />
|the shipping recipient's phone<br />
|-<br />
|shipFax<br />
|the shipping recipient's fax<br />
|}<br />
</center><br />
<br />
===Authorizing and Capturing Payments===<br />
<br />
{{Template:Authorization|merchantLogin|password}}<br />
<br />
<pre>Set Variable $result Value: <br />
CCProcessAuthorizedPayment(<br />
merchantLogin, <br />
password;<br />
previousTransactionId;<br />
dollarAmount)<br />
</pre>CCProcessAuthorizedPayment accepts the same optional parameters as CCProcessPayment.<br />
<br />
<br />
<br />
<br />
=== Using Card Readers ===<br />
<br />
{{Template:Using Card Readers}}<br />
<br />
<pre>Set Variable [$result; Value:<br />
CCProcessPayment(<br />
merchantLogin;<br />
password;<br />
chargeAmount;<br />
"";<br />
"";<br />
"track1=%B1234123412341234^LAST/FIRST/^1112101000000000011100111000000?")]<br />
</pre><br />
<br />
=== Partial Transactions === <br />
<br />
When using CCProcessPayment, specifying the additional parameter "authMode=AUTH_ONLY" will perform an authorization as opposed to a sale transaction. Specifying the "isPartialAuthorization=true" parameter will tell the gateway to allow for partial authorizations of pre-paid credit cards, gift cards and debit cards. <br />
After specifying a partial authorization, you can request the remaining balance and the requested amount by using CCPartialGetRemainingBalance and CCPartialGetRequestedAmount. Both return the dollar amounts, and do not require any additional parameters. <br />
<br />
=== Voiding Transactions ===<br />
<br />
{{Template:Voiding Transactions|merchantLogin|password}}<br />
<br />
{{Template:PayFlow Pro Optional Parameters}}<br />
<br />
=== Crediting or Refunding Transactions ===<br />
<br />
{{Template:Refunds|merchantLogin|password}}<br />
<br />
You can also use CCRefund to do an unlinked credit, which will run a refund of the amount without requiring a transaction ID. Pass in blank values ""; for the previous transaction ID to perform this type of transaction.<br />
<br />
To do an unlinked credit with PayFlow Pro, pass in the blank transaction ID. It will be a little different based on whether it was a swiped or a typed card:<br />
<br />
{|<br />
|-<br />
|''Card Not Present Unlinked Refund''<br />
|''Card Present Unlinked Refund''<br />
|-<br />
| <pre>Set Variable $result Value:<br />
CCRefund(<br />
merchantLogin,<br />
password;<br />
"";<br />
cardNumber;<br />
chargeAmount;<br />
"expirationDate=12/13")<br />
<br />
</pre><br />
|| <pre>Set Variable $result Value:<br />
CCRefund(<br />
merchantLogin,<br />
password;<br />
"";<br />
"";<br />
chargeAmount;<br />
"track1=";<br />
"track2=")<br />
</pre><br />
|}<br />
<br />
== Subscription Services ==<br />
<br />
{{Template:Subscriptions}}<br />
<br />
Payflow Pro supports all five subscription functions. Creating and modifying subscriptions all accept the same optional parameters, available in the table below. In addition, you can specify a trialAmount, which will perform a charge for the amount prior to the start of the subscription as an optional parameter. A final optional parameter is available for subscriptions, called subscriptionMaxFailures.<br />
<br />
Valid pay periods include: week, biwk, smmo, frwk, mont, qter, smyr, and year. <br />
<br />
*WEEK: Weekly - Every week on the same day of the week as the first payment.<br />
*BIWK: Every Two Weeks - Every other week on the same day of the week as the first payment.<br />
*SMMO: Twice Every Month - The 1st and 15th of the month. Results in 24 payments per year. SMMO can start on 1st to 15th of the month, second payment 15 days later or on the last day of the month.<br />
* FRWK: Every Four Weeks - Every 28 days from the previous payment date beginning with the first payment date. Results in 13 payments per year.<br />
* MONT: Monthly - Every month on the same date as the first payment. Results in 12 payments per year.<br />
*QTER: Quarterly - Every three months on the same date as the first payment.<br />
*SMYR: Twice Every Year - Every six months on the same date as the first payment.<br />
*YEAR: Yearly - Every 12 months on the same date as the first payment.<br />
<br />
To create a credit card subscription, use '''CCCreateSubscription.''' To create a bank account subscription, use '''CCCreateSubscriptionACH.''' <br />
<br />
{| class="wikitable"<br />
| <big>CCCreateSubscription</big>|| <big>CCCreateSubscriptionACH</big><br />
|-<br />
|merchantLogin||merchantLogin<br />
|-<br />
|txKey||txKey<br />
|-<br />
|dollarAmount||dollarAmount<br />
|-<br />
|cardNumber||accountNumber<br />
|-<br />
|expirationDate||abaRoutingNumber<br />
|-<br />
|subscriptionName||"";<br />
|-<br />
|numberOfInstallments||accountType<br />
|-<br />
|startDate||accountHolderFirstName<br />
|-<br />
|payPeriod||accountHolderLastName<br />
|-<br />
|"";||subscriptionName<br />
|-<br />
|||numberOfInstallments<br />
|-<br />
| || startDate<br />
|-<br />
| ||payPeriod<br />
|-<br />
| || "";<br />
|}<br />
<br />
''Returns'': The subscription ID on success, "ERROR" if there was a problem.<br />
<br />
After a subscription has been created, it can be modified with '''CCModifySubscription'''. If the original subscription was a bank account you'll use '''CCModifySubscriptionACH'''. The optional parameters can be set to "" if you do not need to modify them. The last two, marked with ""; are payPeriod and frequency, which cannot be modified. <br />
<br />
The trialOccurrences parameter can only be updated if the trial period has not begun or is in progress.<br />
<br />
{| class="wikitable"<br />
| <big>CCModifySubscription</big>|| <big>CCModifySubscriptionACH</big><br />
|-<br />
|merchantLogin||merchantLogin<br />
|-<br />
|txKey||txKey<br />
|-<br />
|previousSubscriptionId||previousSubscriptionId<br />
|-<br />
|''dollarAmount''||''dollarAmount''<br />
|-<br />
|''cardNumber''||''accountNumber''<br />
|-<br />
|''expirationDate''||''abaRoutingNumber''<br />
|-<br />
|''subscriptionName''||"";<br />
|-<br />
|''numberOfInstallments''||''accountType''<br />
|-<br />
|''startDate''||''accountHolderFirstName''<br />
|-<br />
|''payPeriod''||''accountHolderLastName''<br />
|-<br />
|"";||''subscriptionName''<br />
|-<br />
|||''numberOfInstallments''<br />
|-<br />
| || ''startDate''<br />
|-<br />
| ||''payPeriod''<br />
|-<br />
| || "";<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
{{Template:PayFlow Pro Optional Parameters}}<br />
<br />
To cancel a subscription, use '''CCDeleteSubscription''':<br />
<br />
{| class="wikitable"<br />
| <big>CCDeleteSubscription</big><br />
|-<br />
|merchantLogin<br />
|-<br />
|password<br />
|-<br />
|previousSubscriptionId<br />
|}<br />
<br />
'''Returns''': 1 on success, or "ERROR" if there was a problem.<br />
<br />
There are no optional parameters with deleting a subscription.<br />
<br />
== Payment Profiles ==<br />
<br />
Typically, you pass a payment profile ID to the gateway for a Payment Profile. With Payflow Pro, there are no IDs. You can, however, pass in the previous transaction ID and use that to run another charge without having to rekey payment data.<br />
<br />
{| class="wikitable"<br />
| <big>CCProfileProcessPayment</big><br />
|-<br />
|merchantLogin<br />
|-<br />
|password<br />
|-<br />
|"";<br />
|-<br />
|paymentProfileId (previous transaction ID)<br />
|-<br />
|dollarAmount<br />
|}<br />
<br />
{{Template:PayFlow Pro Optional Parameters}}<br />
<br />
==Getting Information==<br />
<br />
{{Template:Getting information}}<br />
<br />
With Payflow Pro, CCLastAVS may be a two character response, as they concatenate the domestic and international AVS together.<br />
<br />
== Getting Help ==<br />
<br />
{{Template:Getting Help}}<br />
<br />
==Troubleshooting==<br />
<br />
* Determine whether the IP address of the machine you are using to process transactions has been added to the list of Allowed IP Addresses in PayPal Manager.<br />
** If you log into PayPal Manager, click the Service Settings tab and click the Allowed IP Addresses link, you will see a screen that allows you enter IP addresses from which transactions may originate. If all of the fields on this screen are empty, then there are no IP address restrictions for the account.<br />
** Do not confuse the Allowed IP Addresses link under the Service Settings tab with a similar link under the Account Administration tab. The latter Allowed IP Addresses link will take you to a screen that allows you to restrict which IP addresses may log into PayPal Manager.<br />
* Determine whether a separate transaction password has been configured in PayPal Manager.<br />
** If you log into PayPal Manager and click the Account Administration tab, you will see a link called Change Password. If you click the link, you will see a screen that will indicate whether a separate password has been configured for processing Payflow Pro transactions.<br />
* "Invalid vendor account" error<br />
** Usually caused when the partner is something other than PayPal and has been omitted or entered incorrectly.</div>Sarah