The v2 farmerswife - Cirkus integration, that was introduced in 6.6 SP1 allows you to:
- New Projects created in farmerswife trigger a new Project created in Cirkus.
- Projects in Cirkus are created with a default or specified Template.
- All new Projects in Cirkus can trigger a new Project created in farmerswife.
- Bi-directional sync of Project custom fields i.e changes can be made in both farmerswife and Cirkus and be in sync.
- Since 6.7 Budget line items can be sent to Cirkus as Tasks, this is covered in another solution article.
- NEW IN 6.8 Bi-directional, or one direction sync of Bookings for synced projects between both systems
NEW IN 6.8 Cirkus to fw sync of Time Reports for Bookings between both systems
NEW IN 6.8 farmerswife Users can be added to a Cirkus Workspace as Members or Resources.
NEW IN 6.8 Cirkus Tasks can be sent back to farmerswife as Project Services/Extras
Note: Since 6.8 Cirkus integration is a licensed option in your farmerswife license. Please contact firstname.lastname@example.org for more information.
TABLE OF CONTENTS
- Migration from old to new Cirkus integration
- New Cirkus Integration Server Setup
- Sync of User and Resources
- Syncing New Cirkus Tasks to farmerswife Project Objects
- Syncing farmerswife Binders to Cirkus Subprojects
- Cirkus options inside of the farmerswife Project window
- Troubleshooting integration issues.
If you don't want to enable the integration and if you want to remove the Cirkus Prompt from your Project Window, go to Toolbox > Settings > Miscellaneous and disable: Show Cirkus Info When Not Setup.
Migration from old to new Cirkus integration
If you are using the existing integration (v1), follow these steps:
1. Disable the v1 farmerswife - Cirkus integration in the Toolbox > Settings tab > Server Setup > Cirkus.com Setup > Disconnect Cirkus Account:
2) Enable the new integration on the Server. If your Server is cloud-hosted by farmerswife, please contact email@example.com
On the farmerswife Server window click on Server Setup > General tab > Cirkus Connector.
Follow now the instructions of the New Cirkus Integration steps below.
Active Projects that are in Cirkus won't be synced again to farmerswife if they already exist in farmerswife.
There are some settings that will smooth the transition from the v1 integration to the v2 integration. See settings below: Cirkus option inside of the farmerswife Edit Project window.
New Cirkus Integration Server Setup
To set up integration got to the Server > Setup > General.
In the Server > Setup > General Tab, there is a new section called Cirkus Connector.
Step 1: Set API Key
This is the key of a user who already registered on Cirkus and has the Administrator role in the Workspace you are integrating.
We recommend that you use a specific integration user for this account i.e firstname.lastname@example.org.
To retrieve the API key, log in to Cirkus as that user, and browse to the User Preferences>API Keys tab.
Type a new name for the key and press Enter.
The key will be created, and you can select to copy the key to your clipboard.
In the farmerswife Server setup window on the General Tab, click on the menu item to the left of the Cirkus Connector, select API Key and paste the key from your Clipboard.
Step 2: Select a Workspace
If you don't have a workspace in Cirkus you will need to create one. Click on the menu item to the left of the Cirkus Connector > Set Workspace. A list of available workspaces is shown, select the one that all the synced projects in farmerswife will connect with.
Step 3a: Configure the options for your Integration - Projects
In the Project Templates section, you can select a Default Cirkus Project Template. All projects that are created in farmerswife and synced to Cirkus will have that template applied. The project templates are set up in Cirkus.
If you create a new Project in farmerswife in the Cirkus section of the Project the Default Template will be selected automatically in the Template selector field. However, you will have to Confirm this selection again when you click OK or Save the Project for the first time. The reason is that you can't change the Project Custom Fields later in Cirkus.
Note: If the "Sync New FW Projects To Cirkus By Default" setting is set to "None", you can select which template is applied to each Project when you chose to sync it!
Map Cirkus Template To FW Project Custom Template
If you use Project Custom Fields in farmerswife you can map those with Cirkus Project Custom Fields. Select the option: Map Cirkus Template to FW Project Custom Template.
First, select a Cirkus Project Template then a farmerswife Project Custom Field Template so both will be mapped. All Custom Fields of both Templates will be shown in one section in the Cirkus Project. Project Custom Fields from Cirkus will show at the top, below farmerswife Project Custom Fields.
Please note, the mapping will only work if you actively select the Project Custom Field Template in farmerswife when you create the Project. It won't work with the default Project Custom Fields that are displayed when creating the Project, even if those are coming from your default farmerswife Project Custom Field template.
You can add various mapping actions, like Cirkus Project template 1 will map with farmerswife Project Custom Field template: Commercial, Cirkus template 2 will map with farmerswife's Feature Film Project Custom Field template and so on.
Here you can select how often the sync will run. The recommended option is every 10 seconds.
Fields To Never Sync to FW
If there are fields that are "master" in FW, you can select to never accept updates on those fields from Cirkus. Project Number is selected by default here.
Active = refers to the Active button in farmerswife and the Open Yes/No slider in Cirkus.
Description = is the Project Note in farmerswife and the description field in Cirkus.
Name = in both cases the name of the Project
Number = in farmerswife this number will be given by default and might be linked to specific project number-creation magic, in Cirkus you can edit this number yourself. If this is set to never sync, even if you gave a specific number in Cirkus, in farmerswife this project will get a new farmerswife Project Number.
Fields to Never Sync to Cirkus
If there are fields that are "master" in Cirkus, you can select to never accept updates on those fields from FW. All your custom fields are available to choose from as well as other fields: Client, Closed, Contact, Email, Note, and Number.
Sync New FW Projects To Cirkus By Default
If this setting is checked, and integration is enabled, then any new Project created in farmerswife will be created in the selected Workspace in Cirkus.
Existing Projects in farmerswife will have a "Cirkus Sync" button in the Edit Project window to create a synced Cirkus project.
If the setting is unchecked, and integration is enabled, new farmerswife Projects will not trigger the creation of a synced Project on creation. However, you can enable manually the "Cirkus Sync" button in the Edit Project window to create a synced Cirkus project.
Auto Create Active Cirkus Projects In farmerswife
If this setting is checked, and integration is enabled, then all active Cirkus projects will be created in farmerswife when you turn on the integration.
Any new projects created in Cirkus will also be created in farmerswife.
Step 3b: Configure the options for your Integration - Bookings
From farmerswife 6.8 it is possible to sync the Bookings between your farmerswife system and your Cirkus Workspace.
- Bookings for people who exist in both your Cirkus Workspace and your farmerswife system will be synced. These users are matched by the email address of the object in farmerswife, and the profile in Cirkus.
- Only Bookings for resources that exist in both your Cirkus Workspace and your farmerswife system will be synced. These Resources are matched by name e.g Avid1 needs to exist as an Object in farmerswife, and a Resource in Cirkus
- Only Bookings for Projects which are synced will be included in the sync.
- Bookings respect the "Sync Mode" set for the integration - see below.
- If the creator of the booking in farmerswife has a Cirkus account, the booking will be created by that user. otherwise it will be the "sync" user (the one linked to the API key)
- Bookings in farmerswife (fw) can have a Booking Name and then Custom Fields associated with it. Similarly, Bookings in Cirkus can have a Booking Template.
When you set or update a Booking Name/Template in either location, it will try to find a matching Name/Template in the other location, matching by exact name.
Among other things, this can be used to get matching colors (based on Booking Name/Template) in fw and Cirkus.
Enable Booking Integration
- To enable Booking sync for new changes, click on Bookings>Sync Enabled.
Note: Bookings created in the initial Sync will not generate notifications, only Bookings created or modified after that time trigger Cirkus notifications.
- If asked by support to assist with troubleshooting, you may need to enable additional logging by clicking on Bookings > Verbose Logging.
Step 3c: Configure the options for your Integration - Time Reports
From farmerswife 6.8 it is possible for Time Reports on Bookings to be synced between farmerswife and Cirkus.
The sync comes with the following limitations:
- If you report more than 24h on a day in Cirkus, it will be capped to 24h in fw.
- If you report on a non-booked day in Cirkus, the time will be registered on the nearest booked day in fw.
- If the Time Report is changed on the same Booking in both farmerswife and Cirkus at the same time, it will not merge the results, but rather overwrite Cirkus' version with the one from farmerswife.
- Time Reports for bookings that exist in both your Cirkus Workspace and your farmerswife system will be synced.
- Only Time Reports for people who exist in both your Cirkus Workspace and your farmerswife system will be synced. These members are matched by email address.
- Only Bookings for Projects which are synced will be included in the sync.
Enable TR Integration
- To activate it, go to Server Setup > General > Cirkus > Time Reports and toggle on "Sync Enabled".
You may also want to click "Detect Timezone" to make sure it detects the correct timezone for farmerswife. If you skip that step, it will automatically try to detect the timezone the first time it syncs Time Reports.
Step 4 Miscellaneous
Change Server URL:
Here you can update the Cirkus URL if you are using an onsite or private Cirkus installation.
The default is https://cirkus.com, the public cloud service.
If you want to point to another Cirkus instance, like a demo, or test environment, change it here.
This is for testing purposes only. Here you can reset the sync - it won't reset your sync settings selected above but will allow you to sync with a new workspace.
A warning window will ask you to confirm this action as this could cause duplicates, etc. You should never use this on the same farmerswife database.
This link will open the cirkus.com site, or the Cirkus mac application if you have it installed.
These settings only apply to the Bookings, Project Custom Field, and the Project Status changes, not about the option if a Project is synced from or to farmerswife/Cirkus.
Bidirectional - This will sync project status and custom field changes made on either platform to the other one.
FW to Cirkus - This will sync project status and custom field changes made on FW to Cirkus only.
Cirkus to FW - This will sync project status and custom field changes made on Cirkus to FW only
Master to Slave - This will sync project status and custom field changes made on the platform where the project was first created, to the other one.
Step 5: Enable Integration
Click on the menu again, and select "Enabled"
Check the status of the connection below the Cirkus Connector logo.
It should say "Connected".
Sync of User and Resources
These options allow you to easily invite the users in your farmerswife instance to collaborate in Cirkus and quickly sync Resources and Objects to Cirkus as "Resources"
Users vs Resources
In some cases however, you may not want your farmerswife resources to be synced to Cirkus as real members who would login to Cirkus, be counted towards user subscription, and receive notifications etc.
Sometimes it can be better to sync Resources to Cirkus Resources, to avoid those side effects.
You can use the setting: in fw Client > Toolbox > Settings > Cirkus (v2) > Map Resources To, for this scenario.
- For customers already using the Cirkus integration it will default to "Cirkus Users", to be backward compatible.
- For all others it will default to "Cirkus Resources".
Anyone who is using the Cirkus integration but not already syncing fw Resources to Cirkus Users can also safely change the setting to "Cirkus Resources".
Syncing New Cirkus Tasks to farmerswife Project Objects
There are two options for syncing work done in Cirkus (Tasks), to financial impacts in the farmerswife Project.
- Budget line items can be sent to Cirkus as Tasks, this is covered in another solution article.
These Tasks always have quantity 1 and are actualized immediately.
- Create Tasks in Cirkus, which will automatically be synced to farmerswife
To use these features we use the Task templates feature in Cirkus, which maps the work done to an Object in farmerswife.
There are two options for the mapping:
Option A) Create a Cirkus Task Template for each Object in farmerswife.
This is a good option if you have a few objects in farmerswife
If a Task doesn't have a mapped Template applied, then the Task will be ignored.
Option B) Create one Cirkus Task Template for all tasks which should be sent to farmerswife. Use a Custom Field selector to define which Object to use.
This is the easiest to set up if you have many objects in farmerswife as you will not need to create a template for each one.
If a Task's Custom Field doesn't contain a valid Object Name then the Task will be ignored.
The farmerswife Project Object's date is the date that the task was completed in Cirkus.
Step 1. Set up the Task Template in Cirkus
Option A) Create a Task Template for each Object in farmerswife.
As Workspace Administrator, go to the Workspace details> Task Templates tab, type the name of the Service you want to make available in Cirkus, and click Add Template
Optionally add custom technical fields, and a field for Quantity, which can be used for the later mapping.
Option B) Create a Task Template for all tasks which should be sent to farmerswife and use a Custom Field selector to define which Object to use.
As Workspace Administrator, go to the Workspace details> Task Templates tab, type the name of the template you want to make available in Cirkus for all farmerswife services and click Add Template
Double click on the template, and go to the Fields tab to add the services Custom Field of type "Selection".
Here you can manually type all the services you have in farmerswife in the Options field, or select bulk edit to paste a list of services from farmerswife.
In farmerswife, you can copy the list from the Object manager, by using the Open As Spreadsheet[^] on the bottom right of the object list, and paste them into Cirkus from there. Optionally add custom technical fields, and a field for Quantity, which can be used for the later mapping.
For more details on Cirkus Task Template setup, refer to the detailed article on the Cirkus support portal
Step 2. Set up the mapping of Cirkus Tasks to farmerswife Objects
In farmerswife go to Toolbox > Settings > Cirkus (v2).
Under Task Template Mappings, add a new mapping using the following fields:
- farmerswife Object Name:
This is the name of the farmerswife Object that will be added to the Project when a new Cirkus Task has been found.
There are two options here based on how you want to set up your Cirkus templates
Option A) If you will use a Task Template from Cirkus for each Service, select a farmerswife Object name here.
Option B) If you will use a Custom field for this, then select the Object Name>From Custom Field
- Cirkus Task Template: This is the Task Template that identifies the Tasks added to Cirkus, so it doesn't just pick up *any* Tasks, only tasks in Cirkus with this Template applied.
There are two options here based on how you want to set up your Cirkus templates
Option A) If you will use a Task Template from Cirkus for each Service, select the template which maps to the Object name selected previously.
Option B) If you want to use a custom field for this, then select the template you will use for all services to be synced.
In both cases, set the following options for how your Tasks and Objects should be Synced
- Cirkus Quantity Field: An optional setting that defines a Custom Field in Cirkus. It then looks at this Custom Field to try to figure out the Quantity for the Project Object that is added in farmerswife.
If not set, the Quantity will typically be 1, but if this field is populated in Cirkus, that is the quantity of that Object that will be added to farmerswife.
- Note Field: This field defines if the Object note will contain some information from the Cirkus task, the options are
1. (Default) "Don't Update" and means it won't populate the Note field on the Project Object with any value.
2. "Task Name", the Note field will get the value "Task Name: (Name of Cirkus task)".
3. "Task Description", the Note field will simply get the same value as the Cirkus Task's Description.
- Actualize (Immediately / When Done): Decides when the added Project Object will get a quantity. If "When Done", the quantity will be 0 until the Task is set as done in Cirkus. If the task comes from a Budget Detail, that quantity will be used. Otherwise, it will try to parse the quantity from the "Quantity Field" as added in Cirkus, or just use 1.
- Pick Up New Tasks Added To Cirkus: If checked, any new Tasks added to Cirkus will be synced to farmerswife. If not checked, new Tasks added there will be ignored.
Step 3. Confirm the integration!
Now when you create tasks in Cirkus using the defined templates these will sync to farmerswife.
The following information is included as part of the sync
1. The Service name
2. The Quantity
3. The User who did the task
4. The Task number
5. The completion date of the Cirkus task (this is the date of the Project Object in farmerswife)
6. Optionally the Note field can contain the Task Name or Task Description, see above Toolbox setting.
Syncing farmerswife Binders to Cirkus Subprojects
It is possible to sync Subprojects in Cirkus with Binders in farmerswife.
Enable this through the following setting fw Client > Toolbox > Settings > Cirkus (v2) > "Sync Binders To Subprojects".
When syncing Tasks from Cirkus to Project Objects in fw, it will decide what Binder to use based on what Subproject the Task is in.
Subbinders are also supported, but as there is not another level in Cirkus, these are mapped as Subprojects with the name of the Parent in the Subproject name.
Project is `Feature Film Pilot` synced in both platforms.
`Episode 1` binder in farmerswife which maps to a Subproject called `Episode 1` in Cirkus.
`Preproduction` is a subbinder of the binder in farmerswife, this is napped to a Subproject called `Episode 1 / Preproduction` in Cirkus
Cirkus options inside of the farmerswife Project window
Cirkus Sync - Sync To Existing Cirkus Project
You can use this option if you need to sync a farmerswife Project to an existing Cirkus project. Once clicked a "Sync To Cirkus Project window appears and lets you select from the drop-down any active Cirkus project.
Once a farmerswife Project is synced with Cirkus "Not Done Tasks:" and "Done Tasks" will show in the Cirkus section of the farmerswife Project indication how many active Tasks you have in the synced Cirkus project and how many Done Tasks. A blue circle icon will show in a pie chart look how many of the Tasks are done by now. Once all are done, the circle will be fully blue.
Canceled Cirkus Tasks will not count here.
You can click on the Cirkus Icon to open the Cirkus project in the Cirkus app.
Note: If you use Cirkus on the web you can change this in a Setting "Open Cirkus Links On Web" in fw Client > Toolbox > Settings > Cirkus (v2), and when this setting is used it causes farmerswife to open Cirkus Links using the web browser instead of the native Cirkus app.
Click on the drop-down menu right before the Cirkus icon will give you some other options if a Project is synced with Cirkus.
It will redirect you to the Cirkus project (either app or web - whatever you have installed) and will let you create a new Task for this Project.
There are four options here:
Reset Warnings and Retry Sync
You can use this in the case of temporary issues, for example permissions issues that are solved, to get the projects in sync again
Force Sync All Bookings: this will scan all bookings in the project and try to resend them to Cirkus.
You can use this in the case of temporary issues, for example permissions issues that are solved, to resend all Bookings
Disable Sync For This Project: Will stop the sync of this Project. Nothing will be updated anymore. You will get the message: Changes Will Apply When Project Is Saved. If you want to re-sync, you will just need to slide the Sync button to the right to reinstate the sync to Cirkus. The link is kept and farmerswife knows to which project in Cirkus this
Forget Sync For This Project: Will stop the sync of this Project and "forget" that it was ever synced, so the next time you want to "re-link" this Project to Cirkus, you will get the dropdown of all available Projects in Cirkus that you want to sync this Project with.
Troubleshooting integration issues.
Project Sync errors
1. Check the Project Window for errors, If there is a yellow warning triangle in the Cirkus area, hover there to see the error and send it to email@example.com
2. Check which user is the one used for the integration, and test the connection from the Toolbox
fw Client > Toolbox > Settings > Cirkus (v2) > [Test Connection]
Client Connection: OK (firstname.lastname@example.org)
Server Connection: OK (email@example.com)
If either of these return failed, check the the user still exists on both systems and that the API key has not been removed.
3. If there is an error with a particular booking or project, confirm that the API user can access that Workspace, Project or Booking
If you are able to resolve a user or permissions issue, you can reset the sync for each project from the project window Cirkus menu >Miscellaneous >
Reset Warnings and Retry Sync
4. If you have access to the farmerswife server, you can confirm that integration is enabled in the server setup . and that the Cirkus Connector says "Connected"
5. Only if directed by the farmerswife support team, in fw Client > Toolbox > Settings > Cirkus (v2) > Logging Settings, Adjust the log level to gather more information.
Note: this can generate a lot of logs and slow down your farmerswife server. Only change these settings if requested by farmerswife support.
User Sync errors
If Bookings for a particular user are not appearing on either side it can be because the user cannot be matched.
Users are synced by email address.
In the farmerswife object manager, rightclick on the user, go to Cirkus. If this option says "Add to Cirkus" it means that a matching user has not been found.
Check the email address of the user matches, including any spaces that might be pasted into the fw object.
When the users are connected the object manager will say "Update in Cirkus".
After the users have been synced, you must force sync bookings either through the Server > Setup > Cirkus menu, or through the Cirkus menu inside the Edit Project window for a specific project to get the previous bookings to be sent.
Any booking that was originally created in fw will be fully updated in Cirkus with the data coming from fw.
This only works in this mode. Not if the booking has been created in Cirkus.
If you still cannot see the Bookings, create a new Booking either system and confirm that is appears in the other one, and consult the server log if they do not.