Page tree
Skip to end of metadata
Go to start of metadata

RESTFul API plugin is used to execute calls to RESTful web services upon form or survey submission and pass collected data within the form or survey inside the API call.

OAuth 2.0 mechanism is used for the users' authentication, meaning clients keys(ID and secret) should be generated for Form.com/Key Survey application by external web-service in order to use this plugin.

To apply this plugin to your form/survey, specify the following parameters:

  1. Logical condition - Specify the logical expression that should be met to send the API call. Use Qx.Ay notation and OR/AND logical operators to create complex logical expressions.
    For Example: Q2.A1 AND (Q5.A2 OR Q5.A3).
  2. Authentication URLOAuth 2.0 authentication endpoint URL. For instance, https://login.salesforce.com/services/oauth2/token
  3. Client ID - Client ID generated by the OAuth 2.0 service and assigned to the Key Survey/Form.com application
  4. Client secret - Client Secret generated by the OAuth 2.0 service and assigned to Key Survey/Form.com application. 
  5. Login - Login name of the end user that will be used for authentication. For the authentication URL above, the login credentials for the Salesforce platform should be specified.
  6. Password - Password of the end-user that will be used for authentication.
  7. Web Service URL - RESTful web-service URL. This field supports piping references, so you may use them to import a value from the form field into the link. 
  8. HTTP Request Method - HTTP Request method that should be used for the RESTful call. You may choose one of the following: POST, PUT, PATCH, GET, DELETE. 
  9. Parameters - Provide the list of parameters that will be sent in the body of the request. 
    • Use the following format to create the list: name=value. For instance, subject=New task.
    • You can use piping references within the value part of the parameter (for example {Q1.A1} may be used to pass the response from the first answer option of the first form/survey question into the request body). 
    • If you need to send the links to the files which were added via File Upload questions, you may use the following tags: LINK:{Qx.Ay} for downloadable links, PLINK:{Qx.Ay} for preview links. The PLINK reference will show a preview of an image, or an icon for other files. You may also use question/answer identifiers instead of Qx.Ay question references, for example: LINK:{aid}

      When an image is accessed by a direct link, a browser will show a download dialog. To view the images right away, place a link to the image inside the <img src='downloadable link'/> HTML tag.

    • The plugin can send the Report by Respondent (rbr) links to an external application along with other data. The parameter for this and its value may be specified in the following way

      Parameter name=Parameter value

      For example, rbr_link=[R]

      The rbr_link parameter name is just an example; you can come up with your own. The following tags may be used as the parameter value: [R], [RnoNav], [RnoHidden], [RPDF]. The difference between these tags is described in the Email Body Text Help chapter ('Email Alert Tags' section).

There is no limit to the number of parameters that can be sent, however, the character limit for all fields in the plugin is 16,000,000 symbols.


Errors processing 

if there are multiple plugins set up in a form/survey, the requests generated by the plugins will be sent via separate queues. These queues are unique per User Identifier and remote URL.

Depending on the received errors codes, messages sending will be retried according to the following rules:

  • Code 500. Module retries to send a request after 1,5,25 min, then every 30 min for 3 hours, and then sends it to the error queue.
  • Codes 408,502,503,504. Module retries to send a request after 1, 5, 25 min, then every 30 min for 24 hours, and then sends it to the error queue.
  • Module retries to send exceptions without code(timeouts, etc.) after 1, 5, 25 min, then every 30 min for 24 hours.
  • Other(404,401) codes are logged as errors and module does not try to send a request again.

For more information, please refer to the following table:

HTTP Code(s)

1st Interval

2nd Interval

3rd Interval

4th Interval

4th Interval Duration

500 (Internal Server Error)

1 minute

5 minutes

25 minutes

30 minutes

3 hours

408 (Request Timeout)

1 minute

5 minutes

25 minutes

30 minutes

24 hours

502 (Bad Gateway)

1 minute

5 minutes

25 minutes

30 minutes

24 hours

503 (Service Unavailable)

1 minute

5 minutes

25 minutes

30 minutes

24 hours

504 (Gateway Timeout)

1 minute

5 minutes

25 minutes

30 minutes

24 hours

404 (Not Found)

Does not Resend

401 (Unauthorized)

Does not Resend

409 (Conflict)

Does not Resend

400 (Bad Request)

Does not Resend

All Other Valid HTTP Codes

Does not Resend

Exceptions without code (timeouts etc)

1 minute

5 minutes

25 minutes

30 minutes

24 hours

The initial request should happen near real time and if a failure occurs, the retry attempts will wait according to the above. Each request that retries will block all other requests for the same end point and the same user that the form belongs to. If there is the same endpoint but different forms that were created by different users – requests will be blocked in separate queues.

Example

Let's explore in more detail how to apply this plugin on the example of the Salesforce and Form.com integration:

 Step 1: Setup necessary parameters within the external application:

  1. Login to the Salesforce. Please note, that you should have a developer's account in order to use this functionality.
  2. In a left pane, navigate to the Build section and click on a black arrow on the left of Create link. Select the Apps option from a list:
  3. Go to the Connected Apps section and click the New button:

    • Provide Connected App name, API name, and Contact email.
    • Check Enable OAuth Settings option.
    • Provide Callback URL, and select Full access(full) option from the Selected OAuth Scopes list and click the Save button.
  4. Click the Setup button on the top:
  5.  In a left pane, go to the Administer section and select Network access option from the Security Controls list:
  6. Click the New button on the right from the Trusted IP Ranges line and specify the Start and End IP addresses of a range that includes your server's IPs. Click the Save button.
  7. From the Force.com Home page go to the Manage Apps:
  8. Find created app under the Connected Apps tab and click on the Manage link.
  9. Then click the Edit button and specify necessary OAuth policies:

  10. When everything is set up, go to the page with your application details(for that, go to Apps page and navigate to Connected apps section) and copy Consumer Key and Consumer Secret (they will be further used as plugin parameters).

Step 2: Apply RESTful API plugin to your form/survey with the Form.com/Key Survey application:

  1. Create your form or survey.
  2. Apply RESTful API plugin from the Workflow section with the following parameters:
    • Logical condition Specify the logical expression based on a form/survey questions that should be met to send the API call. Use Qx.Ay notation and OR/AND logical operators to create complex logical expressions.For example, Q2.A1 AND (Q5.A2 OR Q5.A3).
    • Authentication URL - https://login.salesforce.com/services/oauth2/token
    • Client ID - Type in Consumer Key provided by Salesforce.
    • Client secret - Type in Consumer Secret. 
    • Login - Login that is used for the Salesforce authentication.
    • Password - Password that is used for the Salesforce authentication
    • URL - To create a new task within the Salesforce, use this URL: https://eu6.salesforce.com/services/data/v26.0/sobjects/Task/
    • HTTP Request Method - Select POST method.
    • Parameters - Subject=Test_task; priority=high. 

Once the form is submitted, the following task will be created in a SalesForce account:

Red exclamation mark next to the Subject means that this task has a high priority.

 

  • Please note, that this plugin also works with the question and answer identifiers, so you can use them instead of question and answer numbers in plugin parameters.
  • The RESTful API plugin can only send data to URLs on HTTP ports 80 and 443, FTP port 21.