{"id":15288818,"url":"https://github.com/ka-hq/trophonius","last_synced_at":"2025-07-19T16:06:02.815Z","repository":{"id":59158150,"uuid":"181709826","full_name":"KA-HQ/Trophonius","owner":"KA-HQ","description":"A lightweight, easy to use link between Ruby (on Rails) and FileMaker using the FileMaker Data-API.","archived":false,"fork":false,"pushed_at":"2024-11-18T09:25:48.000Z","size":263,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-20T01:07:00.496Z","etag":null,"topics":["filemaker","filemaker-api","filemaker-data-api","filemaker-dataapi","ruby","ruby-gem","ruby-on-rails"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KA-HQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-16T14:47:19.000Z","updated_at":"2025-01-09T23:18:15.000Z","dependencies_parsed_at":"2024-11-15T05:38:35.008Z","dependency_job_id":null,"html_url":"https://github.com/KA-HQ/Trophonius","commit_stats":{"total_commits":298,"total_committers":6,"mean_commits":"49.666666666666664","dds":"0.43288590604026844","last_synced_commit":"faaf7d2536df596ab8932f6b99c8041bf30d152b"},"previous_names":["willem-jan/trophonius"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KA-HQ%2FTrophonius","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KA-HQ%2FTrophonius/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KA-HQ%2FTrophonius/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KA-HQ%2FTrophonius/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KA-HQ","download_url":"https://codeload.github.com/KA-HQ/Trophonius/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681491,"owners_count":21144700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filemaker","filemaker-api","filemaker-data-api","filemaker-dataapi","ruby","ruby-gem","ruby-on-rails"],"created_at":"2024-09-30T15:53:18.408Z","updated_at":"2025-04-13T08:11:26.672Z","avatar_url":"https://github.com/KA-HQ.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trophonius\n\nA lightweight pure ruby link between Ruby (on Rails) and FileMaker using the FileMaker Data-API.\n\nDo you need support connecting your FileMaker database?\nOr do you have an awesome ruby project in mind?\n\nLet us know if we can help.\n\n[FileMaker Developer](https://kempenautomatisering.com/)\n\n[Ruby (on Rails) development](https://kempenautomatisering.com/Ruby-Development)\n\n# Installation\n\nInstall the gem yourself\n\n```ruby\n gem install trophonius\n```\n\nOr add to your gemfile\n\n```ruby\n gem 'trophonius', '~\u003e 2.1'\n```\n\nAnd run bundle install\n\n# Configuration\n\nTo begin using the gem create a configuration file in the initializers folder called trophonius.rb.\nThis file should contain all the information the Data-API needs to setup a connection to your database.\n\nTo generate this file automatically in a rails app you can use the generator:\n\n```bash\nrails g trophonius --host location_to.your_filemakerserver.com --database Name_of_your_database\n```\n\nWhere --host should contain a url to your FileMaker server and --database should contain the name of your database\n\nExample of the initializer file:\n```ruby\nTrophonius.configure do |config|\n  config.host = \"location_to.your_filemakerserver.com\"\n  config.database = \"Name_of_your_database\"\n  config.username = \"Username to Access the Database\" # or Rails.application.credentials.dig(:username) (requires \u003e= Rails 5.2)\n  config.password = \"Y0urAmaz1ngPa$$w0rd\" # or Rails.application.credentials.dig(:password) (requires \u003e= Rails 5.2)\n  config.count_result_script = \"script that can be used to count the results (optional)\"\n  config.redis_connection = true # default false, true if you want to store the token in redis\n  config.ssl = true # or false depending on whether https or http should be used\n  config.fm_18 = true # use if FileMaker server version \u003e= 18, default true\n  config.debug = false # will output more information when true\n  config.pool_size = ENV.fetch('trophonius_pool', 5) # use multiple data api connections with a loadbalancer to improve performance\n  # USE THE NEXT OPTION WITH CAUTION\n  config.local_network = true # if true the ssl certificate will not be verified to allow for self-signed certificates\nend\n```\n\n# Usage\n\nTrophonius is setup to feel like ActiveRecord. You can choose to create a model for every table in your FileMaker app. Just make sure to include the name of the layout the model should look at:\n\n```ruby\nclass MyModel \u003c Trophonius::Model\n  config layout_name: \"MyModelsLayout\"\nend\n```\n\nYou can also generate a model automatically using the following command:\n\n```bash\nrails g trophonius_model --model MyModel --layout MyModelsLayout\n```\n\nWhere --model should contain the name you want to give to your model and --layout should contain the name of the layout on which this model should be based on\n\n\nOr if your layout contains non-modifiable fields:\n\n```ruby\nclass MyModel \u003c Trophonius::Model\n  config layout_name: \"MyModelsLayout\", non_modifiable_fields: [\"PrimaryKey\", \"RecordID\"]\nend\n```\n\n## Field names\n\nSince FileMaker allows anything to be a field name, Trophonius changes your fieldnames slightly to work like methods for the record. Trophonius changes your field names to a rubystyle, snake_cased name. To retrieve the translations you can use the method MyModel.translations. To use the translations in the create, where and edit methods, Trophonius requires at least one record to exist in order to create the translations.\nThis means that if two of your fields have the same name only one of those fields will be converted to a method, i.e. \"New Field\" and \"New (Field)\" will become both \"new_field\".\n\n## Create records\n\nTo create a new record in the FileMaker database you only have to call the create method:\n\n```ruby\n  MyModel.create(field_one: \"Data\", number_field: 1)\n```\n\nThe new record will be created immediately and filled with the provided data. The fieldnames are the same as the names in FileMaker. If the fieldname in FileMaker contains non-word characters, the fieldname should be in quotes. This method returns the created record as a Trophonius::Record instance. If you have a portal on your layout, you can fill the portal by adding a portal_data parameter:\n\n```ruby\n  MyModel.create(field_one: \"Data\", number_field: 1, portal_data: {\n    \"MyPortalOccurrenceName\" =\u003e [\n      { \"portalField\" =\u003e \"value\" },\n      { \"portalField\" =\u003e \"value2\" },\n      { \"portalField\" =\u003e \"value4\" }\n    ]\n  })\n```\n\nThe field in your portal_data parameter have to be the same as the fieldnames in FileMaker, currently the translations don't work. You should also add\n\n## Get records\n\nTrophonius allows multiple ways to get records. The easiest ways are either .all or .first, which respectively return all records (if you have a foundcount script) or the first 1000000 records or only the first record.\n\n```ruby\n  MyModel.all # all records\n  MyModel.first # first record\n```\n\nIf you want a more restricted set of records or a specific record you might want to use the find functionality. To find a single specific record the .find method can be used. This method requires you to provide the recordid you would like to retrieve from FileMaker. When you want to find a set of records where a condition holds, the .where method should be used. This method returns all records where the condition holds, or an empty set if there are no records with this condition.\n\n```ruby\n  record = MyModel.find(100) # Record with recordID 100 (if available)\n  MyModel.where(number_field: 100).to_a # Records where NumberField is 100 (if any)\n  record.portal.each do |portal_record|\n    portal_record.child_field\n  end\n```\n\nIf a condition requires multiple statements to be true, you can simply add multiple fields in the same where:\n\n```ruby\n record = MyModel.find(100) # Record with recordID 100 (if available)\n MyModel.where(number_field: 100, date_field: Date.today.strftime('%m/%d/%Y')).to_a # Records where NumberField is 100 and date_field contains the date of today(if any)\n record.portal.each do |portal_record|\n   portal_record.child_field\n end\n```\n\n### Omit records\n\nIf you want to find records without the specified query you can use the \"not\" method. This method will add an omit find request to the query. If the query gets executed, FileMaker will return the records where the condition does not hold.\n\n```ruby\n  MyModel.not(number_field: 100).to_a # Records where NumberField is not 100 (if any)\n```\n\n### Or find request\n\n```ruby\n  MyModel.where(number_field: 100).or(number_field: 101).to_a # Records where NumberField is 100 or 101 (if any)\n```\n\n### Sorted find request\n\n```ruby\n  MyModel.where(number_field: 100).sort(number_field: 'ascend').to_a # Records where NumberField is 100 sorted by number_field ascending (if any)\n```\n\n## Update records\n\nTo update the data of a record you can find a record in the FileMaker database and use the assignment operator on it's fields. A field can be accessed in two ways: if the field does not contain any non-word characters it is available as method for the record. Otherwise it is available as a key using the [] operator.\nOnce all fields are set, run the save method to store the new data in FileMaker.\n\n```ruby\n  record = MyModel.find(100) # or use MyModel.where and loop over the RecordSet\n  record.field_one = \"New Value\"\n  record.number_field = 42\n  record[\"Field With Spaces and Non-word Characters!\"] = \"New value\" # or record.field_with_spaces_and_non_word_characters\n  record.save\n```\n\n## Uploading a file to a container\n\nTo upload a file to a container field you can use the upload method on a record. The first parameter, container_name, requires a string containing the name of the container field in filemaker, this process is case sensitive so containerfield ≠ ContainerField. The second parameter is the repetition of the container field (default value is 1). The third parameter, file, is the actual File or Tempfile object you want to upload to your container.\n\n```ruby\n  record = MyModel.find(100) # or use MyModel.where and loop over the RecordSet\n  record.upload(container_name: 'MyContainerField', container_repetition: 1, file: params[:uploaded_file].tempfile)\n```\n\n## Delete records\n\nDeleting a record is as simple as finding the record to delete and calling the delete method:\n\n```ruby\n  record_to_delete = MyModel.find(100)\n  record_to_delete.delete\n```\n\n## Running a script\n\nTo run a FileMaker script from the context of a model you can call the run_script method. This method accepts an optional scriptparameter required by the FileMaker script. The method returns the script result, set by the Exit Script script step in FileMaker.\n\n```ruby\n  MyModel.run_script(script: \"My Awesome Script\", scriptparameter: \"ScriptParameter\") #the script parameter is optional\n```\n\n## Callbacks\n\nA model can have 6 different types of callbacks: ```before_create, after_create, before_update, after_update, before_delete, after_delete```. The callbacks have 2 arguments: a method name or lambda and the arguments to pass to the callback method/lambda. Arguments should be passed as a string.\n\n```ruby\n  class MyModel \u003c Trophonius::Model\n    before_create :run_this_before_created_in_filemaker, [[1, 2, 3], 'second argument']\n    after_create :run_this_after_created_in_filemaker, [[3, 2, 1]]\n\n    before_update :run_this_before_updated_in_filemaker, [[4, 5, 6]]\n    after_update :run_this_after_updated_in_filemaker, [[6, 5, 4]]\n\n    before_destroy :run_this_before_destroyed_in_filemaker, [[7, 8, 9]]\n    after_destroy :run_this_after_destroyed_in_filemaker, [[9, 8, 7]]\n\n    def self.run_this_before_created_in_filemaker(array, string)\n      puts \"#{array.length}, #{string}\"\n    end\n\n    def self.run_this_after_created_in_filemaker(array)\n      puts array\n    end\n\n    def self.run_this_before_updated_in_filemaker(array)\n      puts array\n    end\n\n    def self.run_this_after_updated_in_filemaker(array)\n      puts array\n    end\n\n    def self.run_this_before_destroyed_in_filemaker(array)\n      puts array\n    end\n\n    def self.run_this_after_destroyed_in_filemaker(array)\n      puts array\n    end\n  end\n```\n\n## Scopes\n\nScopes are custom find requests that you define inside your Trophonius models with the ```scope``` method.\n\n```ruby\n  class MyModel \u003c Trophonius::Model\n    scope :my_field, -\u003e { where({ my_field: 'Yes' }) }\n  end\n```\n\n## Date and Time\n\nThe FileMaker Data API requires dates to be formatted as MM/DD/YYYY. To make this easier Trophonius adds \"to_fm\" methods to the Date and Time classes to format these types more easily.\n\n```ruby\n Date.today.to_fm\n Time.now.to_fm\n Date.from_fm(filemakerDateField)\n```\n\n## Disconnecting from the Data API\n\nTo close the connection to the FileMaker server simply call:\n\n```ruby\n  Trophonius::Connection.disconnect\n```\n\n# Upgrading to 2.0\n\nTrophonius 2.0 has been released 🎉\nThis introduced one breaking change: the parameters \"portalData\" for the create and update methods have been renamed to \"portal_data\" to conform to Rubys naming conventions\n\n# To do\n\n- [x] Better portal support (get supported)\n- [x] Support portal set field directly (create)\n- [ ] Support portal set field directly (other actions)\n- [x] Better chainable where queries\n- [x] Omit queries\n- [x] Or queries\n- [x] Store token in Redis\n- [x] More container support\n- [x] Remove non_modifiable_fields requirement from Model\n- [x] FileMaker sorting\n- [x] has_many/belongs_to relationships between models\n- [ ] has_many/belongs_to readme\n\n# Contributing\n\nA contribution can be made by forking the repository. Once you are finished developing/testing in your fork you can submit a pull request.\n\n# LICENSE\n\nThe gem is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT).\n\nCopyright 2019 Kempen Automatisering\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fka-hq%2Ftrophonius","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fka-hq%2Ftrophonius","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fka-hq%2Ftrophonius/lists"}