Cross-Submit (SAM Mini API)
The Cross-Submit functionality allows you to submit data into SAM from another website/system.
It works by re-posting a form's data to a SAM webpage in the background (server-side). This requires a web software developer to setup, but can usually be accomplished within a couple of hours.
By default, the Cross-Submit functionality is disabled, so you must first enable it via the "Forms Security Settings" and then enable it for each form. Then you must "Link Fields" between the two systems. (Please see instructions below.)
The Cross-Submit - Secret Key is an additional level of security for your cross-submit forms. By passing a special secret code along with your data, we can verify that the source is legitimate, to keep out any malicious submits. The default security without a secret key is that the special SAM webpage address has to be known, and by keeping the re-post on the server-side we hide the special SAM webpage address.
Enable Cross-Submit functionality option (First Time Only)
- Security Center
- Advanced Options
- Forms Security Settings
- Edit Settings
- Set Cross-Submit - Enabled to Yes
- Set Cross-Submit - Secret Key (optional but highly recommend, see field hint)
Enable Cross-Submit for a Form
- Open a form in the Form Customizer
- Advanced Options
- Really Advanced Options
- Form Security Settings
- Set Cross-Submit - Enabled for this Form to Yes
- Optional - Set Cross-Submit - Secret Key for this Form - For even higher level of security.
Linking Fields
The names of form fields submitted must match the Field's "DB Column Name" or "Alternate Names" in SAM. You can either rename your form's data, or you can add "Alternate Names" for the fields in SAM. To view a field's "DB Column Name" go to the Field Properties for that Field and click on "View Field Properties" in the Advanced Options, and then look for the "DB Column Name" field.
Add Alternate Names
- Open the Field Properties for an individual Field
- Advanced Options
- Really Advanced Options
- Alternate Names for Cross-Submit
- Add Field - Alternate Names
URL of the SAM Cross-Submit page
The URL of the SAM Cross-Submit page will be the same as its URL when viewed by pressing "Open Public Form" link, except the last 8 characters, will instead be _xin.ashx
For example, if the normal Public Form File name is Inquiry_Form_Edt.aspx, the Cross-Submit file name will be Inquiry_Form_xin.ashx.
To Test: Open the cross-submit URL in the browser, if it opens to a blank white page, then its correct, but if you get an error message, then it means that something is wrong with your URL.
Additional Notes
POST Method required. (Instead of GET)
Firewall of your webserver should allow port 443 outgoing.
The "Cross-Submit | Secret Key" is entered via the "Forms Security Settings" and it can be any alpha-numeric text, like X52Cda12Cdfa231. Pass in the Secret Key via a Query String named "key" (without the quotes).
Connect SAM to Cognito Forms
Redirect an archived public form to a new one
- Open the Public Form in the Form Customizer
- Advanced Options
- Header Footer HTML
- Enter the following into the Header HTML, and replace the Your-Redirect-URL with your actual URL: <% Response.Redirect("Your-Redirect-URL"); %>
NOTE: The basic html tags must remain in the HTML Header and Footer.
Example:
For Header HTML:
<% Response.Redirect("https://agencyname.mysamdb.com/newSAMformtitle.aspx"); %>
<html>
<head runat="server" >
</head>
<body>
For Footer HTML:
</body>
</html>
Now whenever a user attempts to access the old form, it will immediately redirect you to the new URL. Your Redirect URL can be any URL, it doesn't have to be a form in SAM.
Troubleshooting
If you get an error message instead of being redirected, then it most likely means that you have messed up the code. Start over, and make sure that you have your URL surrounded by quotes.
Disabled Forms
Forms that are not Enabled will still redirect, instead of showing the "Form Disabled Error Message".
Comments
0 comments
Please sign in to leave a comment.