Skip to content
+1-888-319-3663

EONE BLOG

Tech Tuesday: How to setup the REST Connector


The REST connector will allow users to integrate to many rest web services.  You will need to refer to the web service api to understand how SmartConnect and the web service you are using need to be setup as every web service is different.

SmartConnect currently comes with some default web services already setup.  This includes Campaign Monitor, Concur, Hubspot, Timely and Zendesk.  These are one click setups to get you going quickly that will setup parameters, return types, methods, and success definitions.  To get started with any of these default web service providers you need to provide your authorization credentials.  Each web service connects differently so you will need to check each web service’s documentation. 

Setting up a custom REST Provider

  1. Open the REST Service Providers window located under the Maintenance Tab>>Service Providers.
  2. Click the Add button to setup a new REST Provider
  3. Enter a Provider Name and setup the following sections for your REST Provider

Parameters – You will need to refer to the API reference to know what parameters you will need.

  1. Click the (+) on the parameters section to setup a parameter. 
  2. Enter a Parameter Name.
  3. Enter the Technical Name.
  4. Enter a default value if this parameter will usually have a set specific value. You will have the option to override this value in the map setup window if the parameter is not a header.
  5. If the parameter needs to be passed in the header mark the Is Header checkbox. You will not be able to override in the map setup window.
  6. Hash Parameter – Not currently used
    HashSecret – Not currently used
  7. Is Timestamp – Enable this option for parameters using dates
  8. Set By Method – Enable this option to query the value from a specific Method currently setup
    1. Choose the Method
      1. Enter the select string – For example, to select the id of a hubspot contact the string would be contact[0].vid. 

Return Types – Refer to you API to know what response format you will need.

  1. Enter a Return Type Name
  2. Select the Return Type Format according to the API
  3. Show Advanced will allow extra processing to be done to get the data from the method. For example, some providers add extra data to the return which will make the json invalid. You can use vb.net or C# to format the data correctly using the Initial Processing section.  This code will run as soon as the method returns a result.  This would be used when you need to run something against all data returned.  Field Value Processing will run every time you try to get a value from the returned json.  Some providers will return all data in an array and this code will allow you to select a single value from the array.
  4. Field Actions
    1. Add The fields that will be used in the response
      To add a parent field, select the Field Actions drop down and select Add Parent Field
      1. Enter the Field Name as found in the API reference
      2. Set the Field Type
      3. Set the Grouping
      4. Mark Show in Data Source if you want the field to show when using this Return Type on a Data Source
      5. If you would like to change the field name enter the value in Overwrite Field Name
      6. Select Token – Allows you to select a defined value from within an array of data.
    2. To add a child field, select a field that will be the parent field and then select the Field Actions drop down and select Add Child Field
      1. Enter the Field Name as found in the API reference
      2. Set the Field Type
      3. Set the Grouping
      4. Mark Show in Data Source if you want the field to show when using this Return Type on a Data Source
      5. If you would like to change the field name enter the value in Overwrite Field Name
      6. Select Token – Allows you to select a defined value from within an array of data.
    3. To remove a field, select the field to be removed and then select the Field Actions drop down and select Remove Field
    4. Load Fields From File – This option allows you to select a JSON or XML file and import the fields rather than adding manually. You will need to go mark the Show in Data Source box for the imported fields as they will not import to show by default.
      1. Select a JSON or XML file that is correctly formatted with the fields needed for the Return Type.


Groups – Groups are used to organize your methods. 

  1. To create a group, click the (+) on the groups tab.
  2. A new blank line will be added to the Group Name column. Enter your desired group name.

Methods – Setup methods available in the web service API being used.

  1. Click the (+) to start creating a new method.
  2. Enter a Method Name.
  3. Select the return type that will handle the response.
  4. Select the Group you would like this method to appear under in the Map Setup window.
  5. Select all the parameters needed for this method.
  6. Enter the URL for the method. You can pass parameters into the URL using curly braces.  For Example, https://api.hubapi.com/contacts/v1/contact?hapikey={hapikey} will pass in the hapikey parameter value.
  7. Enter the appropriate verb for the method: GET, PUT, POST, PATCH or DELETE
  8. Enter the Content Type
  9. Enter the Method Accepts
  10. Select a Success Definition Name – Optional
  11. Mark Show as Source to use this method as a source or mark Show as Destination to use it as a Destination

Method Fields- Add fields to the method that will be requested by the web service when creating data.

  1. Any methods you have created will be available on this tab. Select the method and click the Edit Fields button or double click the method name to edit the fields.
  2. Add fields to the method as defined in the API reference for the specific method.
    1. To add a parent field, select the Field Actions drop down and select Add Parent Field
      1. Enter the Field Name as found in the API reference
      2. Enter the Field Display Name
      3. Set the Value Type as found in the API reference
      4. Mark the required checkbox if the field must be submitted
      5. Enter a Default Value if needed otherwise the mapped value will be used
    2. To add a child field, select a field that will be the parent field and then select the Field Actions drop down and select Add Child Field
      1. Parent Field will auto populate accordingly
      2. Enter the Field Name as found in the API reference
      3. Enter the Field Display Name
      4. Set the Value Type as found in the API reference
      5. Mark the required checkbox if the field must be submitted
      6. Enter a Default Value if needed otherwise the mapped value will be used
    3. To remove a field, select the field to be removed and then select the Field Actions drop down and select Remove Field
    4. After adding a field click Save Method Fields then Update Method Body
  3. Load Fields from File – This option allows you to select a JSON file and import the fields rather than adding manually.

Success Definitions- Handles the response status codes for REST destinations such as OK(200), Forbidden(403), etc.

  1. To create a Success Definition, click the (+) on the Success Definitions tab.
    1. Enter a Success Definition Name – Used to select the definition for methods
    2. Enter a default error message. This is the error that will be displayed if an error is encountered that has not been defined.
    3. Click the (+) button to add status codes.
      1. Select a Status Code
      2. Enter the Error Message you would like to display when the status code is received.
      3. Mark the Successful box if you want the map to report success when the Status Code is received.

7 Comments

  1. Hector M Castaneda on May 29, 2020 at 1:37 pm

    After configure the rest in Smart Connect finish and success record, however didn\’t post to the api call. How I can check is connected to the api call?

    • Ethan Sorenson on July 1, 2020 at 2:26 am

      Hector,
      The easiest way to see exactly what SmartConnect sent to the API, along with the raw response from the REST Service, is to install Fiddler to track https.
      You can download fiddler here:
      https://www.telerik.com/download/fiddler

  2. Adam Grise on August 7, 2020 at 8:21 am

    Hey Ethan, thanks for the article. I’ve got a JSON response from the API I’m connecting to, and when I try to use that and “Load Fields from JSON File” in the Rest Method Return Type dialog, I get a “Object reference not set to an instance of an object” error. Ideas on where that’d be coming from?

    • Ethan Sorenson on August 25, 2020 at 6:49 am

      Adam,

      The JSON parser can fail to parse JSON with 3+ levels. So if you have multiple nested entities within the JSON you can see this error message. As a workaround, I recommend removing anything from the JSON file that you don’t need and trying to upload it again. SmartConnect will only look for the fields in the return type, and ignore anything you don’t reference.

      • Adam Grise on August 28, 2020 at 11:18 am

        Thanks Ethan! I had ended up rebuilding the service provider from scratch and tried it again, and it decided to work. The JSON I have is only 3 levels, so that must not have been the cause. But I’ll remember your advice for future projects!

  3. Joseph Souza on February 1, 2021 at 9:00 pm

    I created the service provider but now how do I use it to call an API? … I am trying the Web Service Connector > Data Source Setup but no relation to the service provider and when I enter the URL of the API without the method, it tells me that it is forbidden but if I enter the method on the URL it says: “The request failed with HTTP status 405: Method Not Allowed.” as I believe it is waiting for a list of methods to load on the next field but does not work.

  4. Jhonatan A. on October 15, 2021 at 7:29 am

    Thanks for the post,
    After I created the rest API, for some reason I can’t see the service provider that I created on the provider selector in the map, is there something else that needs to be done?

Leave a Comment





RECENT POSTS


2021 Q4 Promotions
Connect with us at Directions EMEA 2021 in Milan!
eOne at Summit North America 2021
Employee Spotlight: Megan Tripp, Business Development Representative
eOne is now compatible with Microsoft Dynamics GP October 2021 Release

POPULAR POSTS


2016 SmartConnect Integration Bootcamps
Tech Tues: Automatically refreshing Pivot Tables in Excel Refreshable Reports
Happy Thanksgiving from the eOne team!
2017 SmartConnect Integration Bootcamps
New Releases of Extender and SmartList Builder

CATEGORIES

TAGS

Business Central CRM D365 Business Central Dynamics 365 dynamics crm Dynamics GP Dynamics NAV Econnect Employee Spotlight eone eOne News error Error Message Events Excel Excel Report Builder Extender Flexicoder GP integration Map Meet the Team Microsoft dynamics crm Microsoft Dynamics GP Navigation List Builder Office Relationships partners Popdock release Reporting SalesForce SalesForce.com SmartConnect SmartConnect.com SmartConnect Bootcamp SmartConnect Maps SmartConnect Office Hours SmartList SmartList Builder SmartPost SmartView SQL Tech Tuesday Templates training

Integrate & Automate without Any Code.

SmartList Data has Never Been Faster.

The Easiest Way to Report on GP Data.