{"id":24093230,"url":"https://github.com/umd-lib/wufoo-connector","last_synced_at":"2025-05-07T05:05:58.132Z","repository":{"id":17059769,"uuid":"19824419","full_name":"umd-lib/wufoo-connector","owner":"umd-lib","description":"Middleware to map Wufoo form submissions into others systems (SysAid, etc)","archived":false,"fork":false,"pushed_at":"2020-08-31T17:01:16.000Z","size":94,"stargazers_count":3,"open_issues_count":0,"forks_count":4,"subscribers_count":20,"default_branch":"develop","last_synced_at":"2025-05-07T05:05:50.525Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/umd-lib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-05-15T15:20:51.000Z","updated_at":"2024-10-22T12:46:51.000Z","dependencies_parsed_at":"2022-08-26T07:22:03.857Z","dependency_job_id":null,"html_url":"https://github.com/umd-lib/wufoo-connector","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Fwufoo-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Fwufoo-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Fwufoo-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Fwufoo-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umd-lib","download_url":"https://codeload.github.com/umd-lib/wufoo-connector/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252817010,"owners_count":21808705,"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":[],"created_at":"2025-01-10T09:26:18.192Z","updated_at":"2025-05-07T05:05:58.103Z","avatar_url":"https://github.com/umd-lib.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wufoo Connector\n\nWufoo Connector is a web service designed as a bridge between the Wufoo forms and target applications. Through Wufoo API, the form is integrated with Wufoo Connector. By passing parameters and accessing a designed XSL file, the Wufoo Connector recieves Wufoo form data, re-formates the data and forwards the data to the specified target application. The field mappings between the Wufoo form and the target application are specified in the XSL file. SSDR has implemented the integration of Wufoo Connector to the followig target applications. There is no doubt that the extension to other target applications can be applied.\n\n* [SysAid Ticketing System](https://libticketing.umd.edu/webformsubmit?pageEncoding=utf-8)\n* [AlephRx Ticketing System](http://alephrx.local/cgi-bin/api/reports)\n* Libi Online Student Application \n\n**Warning**: For SysAid integration, it has only been tested using our installation of SysAid Server. It hasn't been tested on SysAid Cloud and may be incompatible. It also may need to be modified for use with other SysAid installations.\n\n  \n## Configuration of Connector\n\nThe web service is a Java web application (wufoo-connector.war) that can be installed and executed under Tomcat, Jetty or other servlet containers. This document focus on the installation and configuration using Tomcat. The configuration using Vagrant virtual machine is also introduced for a local environment.\n\nThe wufoo connector root path is https://\u003cserver-domain-name\u003e/wufoo-connector. The web service request is ~/wufoo-connector/entry/[hash] that is explained in the later section - Wufoo Form Configuration. The connector accesses the XSL file of name **[hash].xsl** at server side, perform the request processing, and then forward the data to target application.\n\nThere is an utility ~/wufoo-connector/upload.jsp to help to upload/download XSL file to and from the server. The configuration of ~/wufoo-connector/xsls context and \"xslDownloadURL\" parameter are for this purpose. (TODO - need to update dependong on the final implementation)\n\n### Tomcat Configuration\n\nConfiguration in Tomcat server.xml:\n\n* Add wufoo-connector web application context\n\n```\n\u003cContext\n     path=\"/wufoo-connector\"\n     docBase=\"wufoo-connector\"\n     reloadable=\"false\"\n     crossContext=\"false\"\n/\u003e\n```\n\n* Map /wufoo-connector/xsls path to a server folder (used by ~/wufoo-connector/upload.jsp)\n\n```\n\u003cContext\n\t docBase=\"/apps/cms/resources/wufoo-connector/xsl\"\n\t path=\"/wufoo-connector/xsl\"\n/\u003e\n```\nConfiguration for Tomcat context.xml\n\n* Add \"xslLocation\" parameter for the location of xsl files\n\n```\nFor example:\n\n\u003cParameter name=\"xslLocation\" value=\"/apps/cms/resources/wufoo-connector/xsl/\" override=\"false\"/\u003e\n\n(where /apps/cms/resources/wufoo-connector/xsl is the folder at the server for all xsl files)\n```\n\n* Add \"xslDownloadURL\" parameter for the location of uploading/downloading the XSL file from the Upload utility (~/wufoo-connector/upload.jsp)\n\n```\nFor example:\n\n\u003cParameter name=\"xslDownloadURL\" value=\"/wufoo-connector/xsl/\"\n\toverride=\"false\"/\u003e\n\t\n```\n\n### Apache Host Configuration\n\nIf the server has Apache as its web server, then add the web application to one of the virtual hosts. Here is an example to add the connector to the SSL of www.lib.umd.edu.\n\n\n```\nFor example: \n\n\u003cVirtualHost 129.2.19.172:443\u003e\n  ServerName www.lib.umd.edu\n  \n  ....\n  RewriteCond   %{REQUEST_URI}    !^/wufoo-connector.*\n  ....\n  RewriteRule ^/(.*)$ http://www.lib.umd.edu/$1 [R,L]\n\n  \u003cLocation \"/wufoo-connector\"\u003e\n    Order allow,deny\n    Allow from all\n  \u003c/Location\u003e\n  .....\n   ProxyPass /wufoo-connector http://localhost:9602/wufoo-connector\n   ProxyPassReverse /wufoo-connector http://localhost:9602/wufoo-connector\n  ....\n\u003c/VirtualHost\u003e\n\n```   \n\n## Deploy Connector to Server\n\n* Download source code from github at [Wufoo Connector](https://github.com/umd-lib/wufoo-connector)\n* Compile the code using\n\n```\nmvn package\n```\n\n* Go to **target** folder in wufoo-connector project and transfer the **wufoo-connector.war** file to the webapps directory on server (/apps/cms/webapps).\n* Start the tomcat server from the folder where tomcat is installed (/apps/cms/tomcat-misc).\n\n```\ncd /apps/cms/tomcat-misc\n./control start\n``` \n\nWhen the connector is running, two types of URL are served:\n \n* ~/wufoo-connector/entry/[hash] - used by Wufoo form to connect to the connector ([hash] is explained in Wufoo Form Configuration.)\n* ~/wufoo-connector/upload.jsp - a utility for uploading/downloading XSL files\n\n## How Does Connector Work\n\nHow to make the Wufoo form work with the connector and a target application? The following two steps are needed to achieve the goal.\n\n* Configration of the Wufoo form\n* The creation and development of XSL file\n  * specify the target application\n  * map how forms are converted into target databases or dataset.\n\n\n### Wufoo Form Configuration\n\nThe Wufoo Form Configuration includes to create a new form, create a Web Hook integration and setup the Web Hook with a target. The target is a URL of Wufoo Connector with parameters. When the form is submitted, the Wufoo-Connector is foewarded. Wufoo-Connector processes the request according to a designed XSL and then forwards the data to the specified target. Here are steps to create and configure the Wufoo form.\n\n* Login to Wufoo form [https://libumd.wufoo.com/login](https://libumd.wufoo.com/login)\n* Create a wufoo form. \n* Create a WebHook Integration for the form\n  * Select \"Notifications\" from Form Manager for the form\n  * Select WebHook from the pull-down list\n  * Select \"Add Integration\"\n  * A panel with type of \"as a WebHook\" will be created\n* Enter parameters for WebHook from the panel\n  * WebHook URL: The URL that Wufoo will send an HTTP POST of the data entered into this form. In this case, it is the URL of a running Wufoo Connector.\n    * Get API Hash Key for the form\n      * Select \"Share\" from Form Manager for the form\n      * Select \"API Informatin\" near the top-right\n      * Retrive the \"Hash\" value (Ex, mvfv3v80rlf7gy)\n    * The URL shall be [wufoo-connector]/entry/[hash]. (Ex, [wufoo-connector] can be https://www.lib.umd.edu/wufoo-connector)\n  * WebHook Handshake Key: This is a a key that you choose as an authentication mechanism to prevent spam to your Web Hook. (TODO - Need information about how the key is generated.)\n  * Check \"*Include Field and Form Structures with Entry Data*\"\n  * Select \"Save\"\n  \n  \n  ```\n  Example:\n  \n  Your WebHook URL: https://www.lib.umd.edu/wufoo-connector/entry/mvfv3v80rlf7gy\n  Your WebHook Handshake Key: testing (TBD - how to generate the key?)\n  \n  ```\n\n### XSL File Creation and Development\n\n#### Initial Sample XSL Creation\n\nWhen a new form is created on wufoo and configuration is complete, the form is ready for connecting to Wufoo Connector. When an entry is submitted from the form, the first entry is a sample entry and will not be submitted to the target application. A sample xsl will be generated based on the fields in the wufoo form called **sample_[hash].xsl**.  The ~/wufoo-connector/upload.jsp utility can be used to check the existance of the file.\n\nHere is an example of sample XSL file. The form contains \"First Name\" and \"Last Name\" two fields.\n\n(TODO - need to replace by a more generic sample)\n\n```\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cxsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\"\u003e\n  \u003cxsl:variable name=\"requestUser\"\u003e\n      \u003cxsl:value-of select=\"//field[@title='First']\"/\u003e\u0026#160;\u003cxsl:value-of select=\"field[@title='Last']\"/\u003e\n  \u003c/xsl:variable\u003e\n  \u003cxsl:template match=\"/entry\"\u003e\n    \u003crequests\u003e\n      \u003crequest\u003e\n        \u003ctarget type=\"sample type\"\u003e\n          \u003c!-- target must include:\n\t\t\ttype = sysaid / alephrx\n\t\t\tdestination URL:\n\t\t\tSYSAID: ( https://libticketingdev.umd.edu/webformsubmit?pageEncoding=utf-8 ) or ALEPHRX: ( http://alephrx.local/cgi-bin/api/reports )\n\t\t\tform ID = form_ID\n\t\t\taccount ID = account_ID\n\t\t\t--\u003e\n          \u003curl\u003ehttp://sample url\u003c/url\u003e\n          \u003cformId\u003esample form ID\u003c/formId\u003e\n          \u003caccountId\u003esample account ID\u003c/accountId\u003e\n        \u003c/target\u003e\n        \u003ccategory /\u003e\n        \u003csubcategory /\u003e\n        \u003ctitle /\u003e\n        \u003cstatus /\u003e\n        \u003cattachments /\u003e\n        \u003curgency /\u003e\n        \u003cpriority /\u003e\n        \u003cdue_date /\u003e\n        \u003cmain_asset /\u003e\n        \u003csubmit_user /\u003e\n        \u003crequest_user_first_name /\u003e\n        \u003crequest_user_last_name /\u003e\n        \u003crequest_user_email /\u003e\n        \u003cusmai_campus /\u003e\n        \u003cassigned_to /\u003e\n        \u003ctechnician_group /\u003e\n        \u003cactions /\u003e\n        \u003clocation /\u003e\n        \u003cdescription\u003eDescription :\n\t\t\tFirst Name: \u003cxsl:value-of select=\"//field[@id='Field2']\"/\u003e\n\t\t\tLast Name: \u003cxsl:value-of select=\"//field[@id='Field1']\"/\u003e\u003c/description\u003e\n      \u003c/request\u003e\n    \u003c/requests\u003e\n  \u003c/xsl:template\u003e\n\u003c/xsl:stylesheet\u003e\n\n```\n\n(TODO - need to explain the structure of the XSL a little bit)\n\n#### Connector XSL Development\n\nThe connector XSL file must be named **[hash].xsl** that is stored at the server location spsecfied in **xslLocation**. You can modify this sample file following the steps below.  \n\n* Download the **sample_[hash].xsl** to local file from ~/wufoo-connector/upload.jsp\n* Rename the XSL file to **[hash].xsl**.\n* Modify **[hash].xsl** (TODO - need to come up a better guideline)\n  * Under the root *Requests* element, create a *Request* element for each field that you wish to be created for a form submission.\n  * Under every request element include a 'target' element which defines the target application URL and other necessary information specific to destination for posting form information.\n\nFor example, in Sysaid we add the following:\n\n      * Url(The location where ticket submissions will be made for your SysAid installation. For us, we use the `webformsubmit` script as part of SysAid's built-in webform processing, but it may vary by installation.)\n\n      * Form Id(A unique key used to authorize requests to your help desk. It will be a series of three hexadecimal numbers separated by colons. These numbers can be positive or negative and are 8, 10, and 4 digits long, respectively.)\n    \n      * Account Id(Your organization's account ID with SysAid. It can be found under the “About” menu in your help desk.).\n\nThe .xsl file contains a placeholder for alephRx request.\nIn AlpehRx we add:\n\n      * Url(The location where ticket submissions will be made for your AlephRx installation.  \n\n * Upload the complete **[hash].xsl** to server using ~/wufoo-connector/upload.jsp\n\n\nA complete **[hash].xsl** example:\n\n```\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cxsl:stylesheet version=\"1.0\"\n    xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\"\u003e\n    \u003cxsl:variable name=\"requestUser\"\u003e\n    \t\u003cxsl:value-of select=\"//field[@title='First']\"/\u003e\u0026#160;\u003cxsl:value-of select=\"field[@title='Last']\"/\u003e\n    \u003c/xsl:variable\u003e\n    \u003cxsl:template match=\"/entry\"\u003e\n        \u003crequests\u003e\n            \u003crequest\u003e\n                \u003ctarget type=\"sysaid\"\u003e\n                    \u003curl\u003ehttps://libticketingdev.umd.edu/webformsubmit?pageEncoding=utf-8\u003c/url\u003e\n                    \u003cformId\u003e1300b3c2:12460019b64:-8000\u003c/formId\u003e\n                    \u003caccountId\u003eumlibraryitd\u003c/accountId\u003e\n                \u003c/target\u003e\n                \u003ctitle\u003esample titile\u003c/title\u003e\n                \u003ccategory\u003eWeb\u003c/category\u003e\n                \u003csubcategory\u003eLibi (Intranet)\u003c/subcategory\u003e\n                \u003crequest_user_email\u003e\u003cxsl:value-of select=\"//field[@title='Email']\"/\u003e\u003c/request_user_email\u003e\n                \u003crequest_user_first_name\u003e\u003cxsl:value-of select=\"//field[@title='First']\"/\u003e\u003c/request_user_first_name\u003e\n                \u003crequest_user_last_name\u003e\u003cxsl:value-of select=\"//field[@title='Last']\"/\u003e\u003c/request_user_last_name\u003e\n                \u003cdescription\u003e\n                    Request User:\u0026#x9;\u0026#x9;\u0026#x9;\u0026#x9;\u003cxsl:value-of select=\"//field[@title='First']\"/\u003e\u003cxsl:text\u003e \u003c/xsl:text\u003e\u003cxsl:value-of select=\"field[@title='Last']\"/\u003e (\u003cxsl:value-of select=\"//field[@title='Email']\"/\u003e)\n\n                    Name of group:\u0026#x9;\u0026#x9;\u0026#x9;\u0026#x9;\u003cxsl:value-of select=\"//field[@id='Field334']\"/\u003e\n\n                    Group description:\u0026#x9;\u0026#x9;\u0026#x9;\u0026#x9;\u003cxsl:value-of select=\"//field[@id='Field335']\"/\u003e\n\n                    Minutes folder:\u0026#x9;\u0026#x9;\u0026#x9;\u0026#x9;\u003cxsl:value-of select=\"//field[@id='Field336']\"/\u003e\n                \u003c/description\u003e\n                \u003cusmaiCampus\u003e\u003cxsl:value-of select=\"//field[@title='USMAI Campus']\"/\u003e\u003c/usmaiCampus\u003e\n            \u003c/request\u003e\n            \u003crequest\u003e\u003c!-- AlephRx request --\u003e\n                \u003ctarget type=\"alephrx\"\u003e\n                    \u003curl\u003ehttp://usmaidev.lib.umd.edu/alephrx/cgi-bin/api/reports\u003c/url\u003e\n                \u003c/target\u003e\n                \u003cname\u003e\u003cxsl:value-of select=\"concat(//field[@title='First'],' ',//field[@title='Last'])\"/\u003e\u003c/name\u003e\n                \u003cfunctional_area\u003eother\u003c/functional_area\u003e\n                \u003ccampus\u003e\u003cxsl:value-of select=\"//field[@title='USMAI Campus']\"/\u003e\u003c/campus\u003e\n                \u003cphone\u003e301-555-0123\u003c/phone\u003e\n                \u003cemail\u003e\u003cxsl:value-of select=\"//field[@title='Email']\"/\u003e\u003c/email\u003e\n                \u003cstatus\u003enew\u003c/status\u003e\n                \u003csummary\u003e\u003cxsl:value-of select=\"//field[@title='Description']\"/\u003e\u003c/summary\u003e\n                \u003ctext\u003etext\u003c/text\u003e\n                \u003csubmitter_name\u003eA.N. Other\u003c/submitter_name\u003e\n            \u003c/request\u003e\n\n        \u003c/requests\u003e\n    \u003c/xsl:template\u003e\n\u003c/xsl:stylesheet\u003e\n\n```\n\n\n## Running on Vagrant (local)\n\nThe connector can be run on a tomcat instance within Vagrant virtual machine.\n\n### Vagrant Configuration\nTo do this, follow the steps:\n\n* Install [Vagrant](https://www.vagrantup.com/) and [VirtualBox](https://www.virtualbox.org/).\n* At local development, chagne directory to vagrant and open **Vagrantfile** (/apps/git/wufoo-connector/vagrant).\n  * Make sure that the webapp path is specified in config.vm.synced_folder property where it points to the absolute path of the maven build target. For example, /users/user/git/wufoo-connector/target or /apps/git/wufoo-connector/target.\n  * The host:\\\u003cport\u003e is specified in config.vm.network prperty. This is the port that Tomcat server will be listening. The default is host:4545.\n\n\n```\nFor example:\nconfig.vm.synced_folder \"/apps/git/wufoo-connector/target\", \"/webapps\"\n```\n\n```\nFor example:\nconfig.vm.network :forwarded_port, host:4545, guest:8080\n```\n* Review tomcat configuration files that are deployed to Vagrant. The files are at ~vagrant/defaults/conf.\n  * Make sure the xslLocation and xslDownloadURL parameters are defined in context.xml\n  * Make sure docBase of /home/vagrant/resources/xsl is mapped in server.xml\n\n```\ncontext.xml:\n\n\u003cParameter name=\"xslLocation\" value=\"/home/vagrant/resources/xsl/\" override=\"false\"/\u003e\n\u003cParameter name=\"xslDownloadURL\" value=\"/wufoo-connector/xsl/\" override=\"false\"/\u003e\n\n```\n\n```\nserver.xml:\n\n\u003cContext docBase=\"/home/vagrant/resources/xsl\" path=\"/wufoo-connector/xsl\" /\u003e\n\n```\n\n### Vagrant Execution\n\nRun \"vagrant up\". This will download the OS for the VM and the required files, and deploy the webapp on a tomcat server running on the VM.\n\n```\n$ cd /apps/git/wufoo-connector/vagrant\n$ vagrant up\n```\n\nThe connector should be running.\n\n* Visit [http://localhost:4545/wufoo-connector](http://localhost:4545/wufoo-connector) and a welcome page is displayed. That means the connector is up running.\n* Visit [http://localhot:4545/wufoo-connector/upload.jsp](http://localhot:4545/wufoo-connector/upload.jsp), upload/download utility, to upload/download xsl files.\n\nWhen the java or jsp code is changed, rebuild the war file and Vagrant war file will be updated too.\n\n(Due to the configuration: config.vm.synced_folder \"/apps/git/wufoo-connector/target\", \"/webapps\")\n\n```\n$ mvn pakcage\n```\nExecute the vagrant provision if any file under ~vagrant/defaults/conf (ex, server.xml, context.xml) is changed.\n\n```\n$ vagrant provision\n```\n\nTo test the connector, follow the steps:\n\n* Upload a valid [hash].xsl that is associated with a Wufoo form\n* Enter data to the Wufoo form and submit it\n* Check if the target application receives the data as expected\n\n\n### Vagrant Machine Environment\n\nTo access shell of the Vagrant machine,\n\n```\n$ cd /apps/git/wufoo-connector/vagrant\n$ vagrant ssh\n(will be at home of vagrant: /home/vagrant)\n```\nTomcat environment\n\n* Tomcat home are /home/vagrant/tomcat7.\n* Tomcat logs are at /home/vagant/tomcat7/logs.\n* Shutdown tomcat by command ~/tomcat7/bin/shutdown.sh\n* Statrt tomcat by command ~/tomcat/bin/startup.sh\n* XSL files should be located at /home/vagrant/resources/xsl.\n\n## License\n\n[CC0](http://creativecommons.org/publicdomain/zero/1.0/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumd-lib%2Fwufoo-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumd-lib%2Fwufoo-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumd-lib%2Fwufoo-connector/lists"}