One of the advanced features available in SmartConnect is the SmartConnect web service. For years we have had this service available for on-premise SmartConnect allowing developers to call SmartConnect integrations remotely. There are countless scenarios where the web service can be used to improve your integration process. Here are just a few examples.
- Configure a webhook in an external application to execute a process when an event occurs. (Similar to the built-in real-time data sources)
- Run a map from Excel, the excel add-in and excel templates both use the web service to run processes
- A file is created in an FTP site everyday as part of a large external process. We don’t know when the file will be available, so at the end of the external process it calls the SmartConnect web service to inform SmartConnect the process can now be run.
Overview
The SmartConnect.com web service is REST web service that runs on the SmartConnect schedule server. The service can be used to perform several actions to both read data from SmartConnect and send data to SmartConnect. Below we will go in detail about the various services available. I have also attached a Postman Collection with an example of all these endpoints.
*Note that after importing the collection you will need to right-click on the collection > Select Edit > Go to the Variables tab and populate the following variables.
- API Url: SmartConnect.com > System API Settings > API Url
- Customer Id: SmartConnect.com > System API Settings > Customer Id
- Username: The email address used to login to SmartConnect.com
- Password: The password used to login to SmartConnect.com
- Token: Token can be left blank, because one will be generated in the GetToken step
Authentication
As with most web services, the trickiest part is getting the Authentication configured correctly. SmartConnect.com uses a Token for authentication. Generating the token is simple if you have all the necessary information. Here is some basic information about the tokens.
- Tokens are Company specific. If your username has access to multiple companies, you will need to generate a separate token for each company.
- Tokens are valid for 3 months
GetToken
The GetToken endpoint requires 3 parameters. To generate a token.
- password
- companyID
If you don’t want to send a plain text password, you can encrypt and encode it using the script below.
var hash = CryptoJS.HmacSHA256(“{{Password}}:6clDgmNok3WtR8GKYW6N”, “6clDgmNok3WtR8GKYW6N”);
var hashInBase64 = CryptoJS.enc.Base64.stringify(hash);
The postman collection sets the token to an environmental variable named ‘Token’ so after running the GetToken process once all maps that require a token will automatically have the variable.
POST {{API Url}}/GetToken?email={{Username}}&password={{Password}}&companyID={{Customer Id}}
Validate
The Validate endpoint will return a Boolean to inform the client whether the token is valid or not.
POST {{API Url}}/validate?token={{Token}}
Map Information
Map information will provide details about the existing maps in SmartConnect.com
GetMapList
Retrieve a list of processes in SmartConnect.com.
POST {{API Url}}/GetMapList?token={{Token}}
GetMapColumns
Retrieves a list of all source columns in the data source.
POST {{API Url}}/GetMapColumns?token={{Token}}&mapKey={{mapKey}}
GetMappedMapColumns
Retrieves a list of all destination columns that have been mapped.
POST {{API Url}}/GetMappedMapColumns?token={{Token}}&mapKey={{mapKey}}
Map Data
Map Data will return the current data in the data source of the specified process.
GetAllData
Returns the current defined source for the specified process.
POST {{API Url}}/GetAllData?token={{Token}}&mapKey={{mapKey}}
GetAllDataWithVariables
Returns all data from a process source while providing a global variable for the source query. Provide the variables in the body.
POST {{API Url}}/GetAllData?token={{Token}}&mapKey={{mapKey}}
[{"Key":"GBL_TEST","Value":"107210"}]
Map Runs
RunMapDataTable
Runs a specified process with the provided data table.
POST {{API Url}}/runmapdatatable?token={{Token}}&mapkey={{mapKey}}
<RequestData>
<Table>
<accountnumber>C00070</accountnumber>
<CustomerID>ID</CustomerID>
<name>Test Account 001</name>
</Table>
</RequestData>
RunMapDataTableWithErrors
Runs a specified process with the provided data table and returns validation errors from validation tasks.
POST {{API Url}}/RunMapDataTableWithErrors?token={{Token}}&mapkey={{mapKey}}
<RequestData>
<Table>
<accountnumber>C00070</accountnumber>
<CustomerID>ID</CustomerID>
<name>Test Account 001</name>
</Table>
</RequestData>
RunMapXml
Run the specified process with the provided payload. Inside the XML tags needs to be XML encoded.
POST {{API Url}}/runmapxml?token={{Token}}&mapkey={{mapKey}}
<RequestData xmlns_i="http://www.w3.org/2001/XMLSchema-instance">
<Variables/>
<Xml><DataSet>
<Table>
<accountnumber>C00070</accountnumber>
<name>Test Account 001</name>
</Table>
</DataSet>
</Xml>
</RequestData>
RunMap
Run the specified process now.
POST {{API Url}}/runmap?token={{Token}}&mapKey={{mapKey}}
RunMapWithVariables
Run a specified process while providing global variables.
POST {{API Url}}/RunMapWithVariables?token={{Token}}&mapKey={{mapKey}}
[{"Key":"GBL_TEST","Value":"False"}]
SaveProcessErrors
Saves Process Errors on the SmartConnect server from a previous run. Will return a success Boolean. You can find the tenant information by going to SmartConnect.com > Processes > Error Processing > ‘Select Columns’.
{{API Url}}/SaveProcessErrors?token={{Token}}&mapKey={{mapKey}}&tenantServer={{tenantServer }}&tenantTechnicalName={{tenantTechnicalName}}&runNumber={{runNumber}}
SmartConnect.com Web Service Collection
Conclusion
The SmartConnect API can be very powerful tool in your toolbox if you are aware it is there and put it to use. If there is any functionality you would like to see added to the web service, make sure you submit a suggestion as a Feature Request.
If you have any more questions, feel free to reach out to us at support@eonesolutions.com
