Integrate with external systems

Most applications, and business applications in particular, will need to communicate with one or more other systems such as CRM, ERP, or Accounting systems. Appfarm offers built-in components for setting up integrations towards external systems, as well as running server-side jobs or setting up API endpoints.

In general, there are main categories of integrations:

1. From Appfarm to a third-party system

2. From a third-party system to Appfarm

Integrate from Appfarm to a third-party system

This means that the integration initiates from Appfarm, meaning a request (GET, POST etc) is sent from Appfarm to the external third-party system.

You may fetch data from, or push data to external APIs, by using the Web Request Action Node. It may be used both from your Apps (for example get or post some data when clicking a button), or from Services (for example, get new and updated orders every 5 minutes).

The Web Request is documented in our Action Node Library. Please read this documentation if you want to initiate an integration from your App or Service!

Integrate from a third-party system to Appfarm

This means that the integration initiates from the third-party system. In this case, the third-party system cannot send that request to our App, since our App only lives in the local browser client side. We need an endpoint that lives server-side. In Appfarm, this is either a Service Endpoint or a GraphQL Endpoint.

Service Endpoint

Use Services to create tailored APIs for external consumers. You may create a Service Endpoint, and give access to external parties by creating a Service Account and an API key for the external parties.

A Service Endpoint for receiving data (an incoming POST request) may be set up with a mapping of the incoming Body Data towards your data model (similar to the Result Mapping of the Web Request), and the Service Endpoint can trigger an action for processing these data.

A Service Endpoint for sending data back (an incoming GET request), can be set up with a mapping of Query Parameters. An action may read the data to be returned, and the Service Endpoint defines which data sources or JSON structure to send back once the action is completed.

Accessing a Service Endpoint

You may access and test your Service Endpoints using the API Explorer.

For a third-party system that wants to go a GET operation towards a Service Endpoint in Appfarm, you need to set up an API Key first, and then connect using this configuration:

• URL: https://SOLUTION-HOSTNAME/api/services/SERVICE-ALIAS-SLUG/READABLE-ID

• Authorization:

  • Option 1 (Recommended): Add a header entry with key Authorization and value Bearer <API-KEY-HERE>.

  • Option 2: Add the API key as a URL parameter named token, resulting in a URL such as https://SOLUTION-HOSTNAME/api/services/SERVICE-ALIAS-SLUG/READABLE-ID?token=<API-KEY-HERE>.

GraphQL Endpoint

Object Classes in the Global Data Model support enabling GraphQL APIs for your data defined in the Data Model. GraphQL is a query language for APIs, enabling the consumer to define exactly what data they need. See our documentation of GraphQL for more info.

By turning on GraphQL for an object class, Appfarm generates this API for you, based on your Data Model. Appfarm's security layer will always be on top of your data so that the users without required permissions are not able to use these APIs to fetch data they should not have access to.

Accessing a GraphQL Endpoint

You may access the GraphQL editor of your environment by clicking the Explore GraphQL button in the top bar of the Global Data Model in Create.

For a third-party system that wants to go a query towards a GraphQL Endpoint in Appfarm, you need to set up an API Key first, and then connect using this configuration:

• URL: https://SOLUTION-HOSTNAME/api/graphql?query=YOUR-GRAPHQL-QUERY-HERE

• query: With reference to the above URL, you need to input the GraphQL query. The content of this query is dependent on the data you want to access. Example: The query {projects}gives you all Projects (with all properties) in a solution with Projects enabled for GraphQL access. Please read more about queries here.

• Authorization:

  • Option 1: Add a header entry with key x-af-api-token and the API key as value

  • Option 2: Add the API key as a URL parameter named token, resulting in a URL such as https://SOLUTION-HOSTNAME/api/graphql/?token=API-KEY-HERE&query=YOUR-GRAPHQL-QUERY-HERE