While we can’t offer you advice in terms of how to program your web service, below are some tips on how to best configure and test your work.
Re-running REST connectors
When testing out your web service against incoming data from our platform, you’ll likely need our platform to send the same REST request over and over.
Requests are generated from our platform by the REST connector’s triggering event – e.g. by a new Form entry being captured.
Capturing a new Form entry every time you want to test a REST request will be time-consuming, so instead, you should rather reschedule a REST connector against an existing entry. This way you can run the same REST connector job over and over again.
To reschedule a Form entry connector:
- Go to the Data area of the taskform web platform and search for your target Form entry
- Mouse over the target Form entry row in the Data listing, and click the “logs” link to show the Logs dialog.
- The Logs dialog shows you the various connector jobs run for the entry, including your REST connector.
You can reschedule the REST job by mousing over the REST connector log line and clicking the “reschedule” link.
Use RequestB.in to view REST requests sent by our platform
If you’re not sure what exactly is being sent by our platform to your service, then a service like requestbin.com provides a simple, free way to see the exact data sent.
RequestBin (and similar services) gives you a URL that will collect requests made to it and lets you inspect them in a human-friendly way.
The steps to set-up are simple:
- Head over to RequestB.in and create a RequestBin. Make sure you tick the “Private” checkbox to keep your data safe.
- Point your REST connector at the RequestBin.com URL and trigger your REST connector (e.g. by capturing a new Form entry or by rescheduling the connector on an existing entry)
- Give the connector a minute to be run and then review the REST request information over at your private RequestBin URL.
Should you use a custom REST body or not?
By default, our REST connectors will send data in one of our standard answer formats.
If you want to connect a REST connector to an existing API on your systems, then you must specify a custom body on your REST connector, since our standard formats will not be compatible with your API.
Custom bodies are dynamically generated by our system against a JSON/XML template that you specify. The relevant answer/data values are injected into your template by using our standard Data Template syntax; this concept works similarly to a “mail merge” in Word.
You should definitely review our Data Templates documentation to understand how to handle concepts like repeating data. See the “Outputting Data with Templates” section for more.
Custom bodies can take a while to get exactly right, usually through much testing, but this does provide the most flexible way to integrate with existing APIs and services.
If you are building a brand new web service from scratch, then we recommend you build your web service to work with one of our built-in answer formats.
This will save you time in terms of having to design your own request format; instead, you can just work with ours immediately.
We provide three standard formats for outputting Form entry data:
- “Flat” – provides a flatted output of Form entry data
- “Rich” – provides a detailed hierarchical data output
- “Raw”- provides a minimal hierarchical output
You can view these formats in action by choosing a format from the given dropdown on your REST connector, then testing the connector to gather the request result (e.g. using RequestBin.com above).
Another way to view these formats in action is via the API Explorer.
Head over to the FormEntry/Search endpoint and use the AnswerFormat parameter to specify the desired response format.
Using SOAP XML
Our platform supports the use of SOAP XML in REST Connectors to POST or PUT to external APIs.
A SOAP message is an ordinary XML document containing the following elements:
- An Envelope element that identifies the XML document as a SOAP message
- A Header element that contains header information
- A Body element that contains call and response information
- A Fault element containing errors and status information
In order to use SOAP XML, you will need to customize the header of your POST or PUT request on your REST Connector.
- Set the HTTP Action to POST or PUT and Data As to XML.
- Enter the Destination URL.
You can test the example SOAP XML body we’ve provided below by using the Destination URL http://www.example.org - Click the “Customize Headers” link at the top of the connector
Enter both a Name and a Value for SOAP XML :
Name: Content-Type
Value: application/soap+xml - Click the “Customize Body” link at the top of the connector
Enter a customized body for the SOAP XML. An example SOAP XML script is provided below the images here
Example SOAP XML Body
The following script is an example of the SOAP XML you can place in your REST connector body:
<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"
soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
<soap:Body xmlns:m="http://www.example.org/stock">
<m:GetStockPrice>
<m:StockName>{{yourFieldOne}}</m:StockName>
<m:StockName>{{yourFieldTwo}}</m:StockName>
<m:StockName>{{yourFieldThree}}</m:StockName>
</m:GetStockPrice>
</soap:Body>
</soap:Envelope>