Comment on page
Web request
The Web Request Action Node is a generic component used to integrate with other systems. The component lets you integrate with all modern API endpoints, such as Slack, Jira, Microsoft Dynamics, Google Cloud, etc.
An important part of integrations is to know the system you want to integrate towards. Most modern systems provide a (REST) API and documentation of the various endpoints you may access, as well as the format of its input and response.
A good approach when it comes to integrations is to use an external tool, such as Postman, in order to test communication towards the external system. Postman is quite easy to get started with, and once you've successfully managed to do a request in Postman, it's fairly straightforward to set this up in Appfarm!
In this section, we will describe the different settings of the Web Request Action node, followed by some practical examples.
The address to the endpoint you want to communicate towards. This is normally defined by the API documentation of the external system.
Path parameter
Often, the URI/URL contains some dynamic parts, called path parameters. In that case, the URL should be set using the Function Editor.
Example
When fetching company information about companies from the Norwegian government, the API link might look like this:
The URL has one static (https://data.brreg.no/enhetsregisteret/api/enheter/) and one dynamic part (919697199). In this example, you might set the URL by using the Function Editor, adding the company organization number as a variable, and returning the URI + variable.
return "https://data.brreg.no/enhetsregisteret/api/enheter/" + orgNumber
Sometimes, the API we are calling has parameters in the URI. In the above example, the external API might define that you may send a parameter "OrgNo" as a parameter instead. You may add "OrgNo" as a Query Parameter in the web request, and set the value to Company.OrgNumber.
If the base URI is "https://data.brreg.no/enhetsregisteret/api/enheter", adding a Query Parameter "OrgNo" will in fact produce a URI such as: "https://data.brreg.no/enhetsregisteret/api/enheter?OrgNo=919697199".
Add Custom Header tags to your Web Request.
In some cases, the external application requires some headers. Request Headers are, opposite to Query Parameters, not part of the URL. They are part of the header of the request.
This is where you set up the Authorization normally required by the external system.
There are primarily two types of authorization: Basic and Bearer. When testing in Postman - you see them in the Authorization section. Basic allows you to input a username and password, whereas Bearer allows you to enter a token.
When using Basic Authorization, you should add the Username and Password here. Note: These should be stored as Secrets in Appfarm Create, and these Secrets should be selected in this action node.
When using Bearer Authorization, you should add the bearer token here. Normally, you would also tick the option "Prefix bearer keyword" (the header will then be 'Bearer <YOUR_TOKEN>')
Note: A Bearer token is normally not static, and must be retrieved and stored on a schedule.
For other types of Authorization (other than Basic or Bearer), you may use Request Headers.
Defined by the external API. Possibilities: GET, POST, PUT, PATCH, DELETE. GET and POST are by far the most used.
A GET does not send "Body Data" - and is normally used for sending a request in order to receive some information from another system
A POST sends some "Body Data". Changing the method from GET to POST will reveal the possibility to set the Body Data of the web request. POST is normally used for sending data to another system.
Here you will need to create a JSON string with a structure defined by the external system. You will typically use a function for creating this. An example for sending order status 2 for a given Order to another system:
// orderID has been added as a function parameter
return `{ "ExternalOrderID": ${orderID}, "Status": 2 }`;
When performing either GET or POST operations - the other system might send some data back, typically in JSON format. Appfarm supports JSON "out of the box", but in cases where SOAP (old web services/xml) is used, you may transform the result to JSON first using the Result Parser (not demonstrated here).
Looking up company info with a GET web request, might send back the following JSON-formatted structure (defined by the external system API, or as seen when playing around in Postman), in this case a simplified example:
{
"orgNo" : "919697199",
"name" : "Appfarm AS",
"orgType" : {
"code" : "AS",
"description" : "Aksjeselskap"
},
"addresses": [
{
"country" : "Norge",
"line1" : "Torggata 15",
"postalCode": "0515"
},
{
"country" : "Norge",
"line1" : "Dummy street 1",
"postalCode": "0515"
}
]
}
Setting up the Result Mapping:
First, add an item. You normally just need 1 item. 1 item allows you to map properties of the received JSON structure to a data source.
- Root path: If you want to start looking up properties at a level deeper down in the structure than the root level. Typically - leave it blank.
- Data source: This needs to be a runtime-only data source. If the data you receive is a list (e.g. a list of orders) - select a runtime only "Orders" data source with cardinality many. In the example above, add a runtime-only data source "Company" (single cardinality).
- Nested Data Mapping: If the response contains nested structures (such as a list of Orders, and for each Order - a list of Order Lines) you may use Nested Data Mapping for first map Orders, and then map Order Lines - and connect these two together. You would need to define the "Root path" at the top level (e.g. to "orders"), and for the Nested Data Mapping - define the "Path" (e.g. to "orderLines") and the "Root Connection" (e.g. Order Lines (temp).Order).
- Automap Node Names: If the name of the properties of the JSON returned by the web request matches the node name of the Object Class Properties of the Appfarm Data Source - you may tick Automap Node Names. This will simply autofill the Property Mapping with the node names of the Object Class Properties.
- Property Mapping: See the illustration below. Note the [] expression in the received JSON. This implies a list, and we might access the property "line1" of the first item in the list by stating "addresses.0.line1"
Notes to the Property Mapping in the example above:
- By defining a root path, the property mapping will start at the first level of "children" of the root path. E.g. if the root path was set to "orgType" in the above JSON example, you could map the object class property Org type simply by referencing "description".
- If the root path holds a list of objects (as is the case for "addresses" in the JSON above, as seen by the square brackets), the Data Source set in the Result Mapping must be of cardinality "Many". E.g. if the root path is set to "addresses" in the above JSON example, we might set the Data Source to "Addresses (temp)" (a runtime-only, multi-cardinality data source), and the property mapping would be "line1" and "country" - resulting in "Addresses (temp)" to be populated with 2 objects.
- As seen in the illustration above, we set the property mapping to "addresses.0.line1" and "addresses.0.country". Since the "addresses" node has a list of objects as children - this is a syntax for just retrieving the properties of the first child (the first address in the list).
A web request is by default sent from the server - e.g. when initiated from an app, the request is sent to the Appfarm server before it is sent to the actual destination. The reason is both that the passwords may be stored as "Secrets" in Create, allowing for them to be used without sending them to the clients, and that this allows for providing your integration with a static IP (some external infrastructures require firewall opening in order to allow for integrations.
When you tick "Send from client" - you send directly from the client. In some cases, this may reveal a more detailed log if something fails. Send from client is normally used for debugging. Note that when "Send from client" is ticked, you need to add the host name to the "Allowed web request targets" section in Create -> Config -> Environment Config (for each environment).
Explained above and only possible when a web request is NOT sent from client.
This feature must be enabled by Appfarm, and will route all requests from a proxy static IP address (35.233.86.224).
This is the content type for the Body of a POST request. The default setting is JSON, but if the external system requires some other content type, this might be adjusted here.
Normally no need to set, the default is JSON, but it may be overwritten (e.g. an Array buffer for receiving files and converting the binary data to a base64 string). Note that you may use the Create file object action node with Source Type "URL" for downloading a file from a URL and uploading it into your own file object class.
The Result parser (if set) is applied before the Result Mapping is executed.
Result parser is normally used when the response contains xml - i.e. when dealing with SOAP endpoints. The Result parser may also be used if - in some cases - the JSON response of the external system is not possible to map directly using the Result Mapping. In such cases, you may use a result parser to transform the received JSON into another JSON format, or to add other properties to the JSON before doing result mapping.
Example
If the response contains the following JSON:
{ "CompanyName": "Appfarm", "OrgNo": "123456789"}Using a Result parser, the rawResponseData is a JSON object containing the value above.
If we want to add a property "CompanyStatus": "active" to the JSON before the Result mapping is done, you may add a Result parser with the following function:
rawResponseData.CompanyStatus = "active"return rawResponseDataInside the Result parser, the parameter rawResponseData holds the response received from the web request. You may use javascript to transform it. The result parser should always return a valid JSON structure, and the JSON structure returned from the Result Parser should be mapped in the Result Mapping.
When testing your Web Request, you may inspect the actual response received, or the request sent using the Console log in your browser.
Debugging a web request using the Console log
In the above screenshot, you may see the log for a the Web Request when doing a POST operation. The JSON
{"Test": "OK"} is sent in the Request. By expanding the log-entry named
payload, you may inspect the Header, URL and Body of the Request, as well as the StatusCode and Body of the Response (depending on whether a POST or GET is performed).When the other system has a SOAP endpoint, an XML structure must be sent, and XML will be received. You should try to set up the request in Postman - if you succeed, it's basically a matter of setting up the Result parser.
Method
Must be set to POST, even if you are only querying data.
Body Content
An example of the function for the Body Content:
return `
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://accountingsystem.com/webservices">
<soapenv:Header/>
<soapenv:Body>
<web:Login>
<web:credential>
<web:ApplicationId>${applicationId}</web:ApplicationId>
<web:IdentityId>${identity}</web:IdentityId>
<web:Password>${password}</web:Password>
<web:Username>${username}</web:Username>
</web:credential>
</web:Login>
</soapenv:Body>
</soapenv:Envelope>
`
Request Headers
Some headers are normally required. An example: A header with a key "SOAPAction" and value "http://accountingsystem.com/webservices/login".
Result Parser
The rawResponseData contains an XML. Here's an example of the result parser, when the response from the Login request is an xml:
var parser = new DOMParser();
var doc = parser.parseFromString(rawResponseData, "text/xml");
return {
sessionId: doc.getElementsByTagName("LoginResult")[0].textContent
}
Result Mapping
Same as for REST integrations. In the example above, the returned structure from the Result parser is
{
sessionID: "<some-id>"
}
You would just need to map "sessionID" to your object class property in the Property Mapping section.
Last modified 1mo ago