Welcome to the comprehensive guide on building your own integration with Altan. If you haven’t yet, it’s highly recommended that you first read the Altan Integrator Overview to familiarize yourself with the key concepts like External Apps, Connection Types, Action Types, Resource Types, and Webhooks.This guide will walk you through every step of creating a custom integration, from defining apps to setting up API calls and resources.
🛠 Step-by-Step Guide to Creating Your Integration#
Integrating third-party apps into Altan involves two key steps:2.
Configuring the app using the Integration Creator or manually in the editor.
1️⃣ Create a Custom App#
Navigate to the Custom Apps Tab#
1.
Go to the Custom Apps tab in the Integration section of Altan. 2.
Click Create Custom App to start.
Define the App Details#
Name: Enter a meaningful name for your app, e.g., "Facturit."
Description: Provide a short explanation of what the app does, e.g., "Handles invoice parsing and uploads to spreadsheets."
Icon URL: Paste the URL of the app’s icon.
Automatic Setup#
Clicking Create will automatically generate:A new External App entry.
A Connection Type linked to the app.
Note: Currently, each app can only have one connection type. All the logic (authentication, actions, resources, and webhooks) will reside within this connection type.
Once created, your app will appear in the Custom Apps list. Double-click on the app to enter the App Editor, where you can configure the connection type.
From the App Editor, you can manually configure the following components:Authentication#
Define how users will authenticate with the app. Altan supports various authentication methods such as OAuth, API Keys, and Basic Authentication. These are set at the Connection Type level.Actions#
Actions define the API calls the app can make. For example:Fetching data from an external system.
Resources#
Resources represent the structured data returned by an API call or required as input. For example:A JSON object representing an invoice.
A response object containing user data.
Webhooks#
Webhooks allow real-time updates by notifying Altan of specific events in the external app (e.g., "new email received" or "file uploaded").
3️⃣ Use the Integration Creator for Easier Setup#
The Integration Creator simplifies the process of defining actions and resources. Here’s how you can use it:Navigate to the Integration Creator#
Select Connection Type and Base URL#
Connection Type: Select the app you just created.
Base URL: Enter the base URL of the external app's API.
Parse OpenAPI Schema#
Paste the OpenAPI schema (in JSON format) into the editor.
The system will automatically extract:Actions: API calls that can be executed.
Resources: Data structures returned by the API.
For example, a schema might define an action like "Fetch Invoice" and a resource type called "Invoice Object."
Upload Actions and Resources#
Review and edit the details as needed.
Click Upload All to publish actions and resources to your integration.
4️⃣ Defining an Action Type#
An Action Type specifies how the integration interacts with third-party APIs by defining API calls. It contains the following key fields:Name: A descriptive name for the action, e.g., "Parse HOCR Page With Payload To Sheets."
Description: (Optional) A short explanation of what the action does.
URL: The endpoint of the API call (e.g., /misc/parse-hocr-page-with-payload-to-sheets).
Method: The HTTP method used for the request (POST, GET, PUT, etc.).
Parameters#
Define the request structure:Headers: HTTP headers required for the API call.
Body: The payload sent with the request.Use $ref: ResourceTypeName to reference a Resource Type from the same connection type.
Path Params: Parameters embedded in the URL (e.g., /user/{id}).
Query Params: Key-value pairs in the URL query string (e.g., ?key=value).
Output#
Define the structure of the data returned by the API.
Example: Parsing HOCR to Sheets#
Here’s an example action setup:Action Fields#
Name: Parse HOCR Page With Payload To Sheets
URL: /misc/parse-hocr-page-with-payload-to-sheets
Parameters#
{
"type": "object",
"properties": {}
}
{
"$ref": "ParseHOCRPageWithPayloadToSheetsRequest"
}
{
"type": "object",
"properties": {}
}
{
"type": "object",
"properties": {}
}
5️⃣ Testing Your Integration#
After setting up the integration:1.
Use Altan’s debugging tools to verify that the actions and resources work as expected.
2.
Test webhook events for real-time updates.
🎯 Key Takeaways#
Custom Apps provide the framework for building integrations.
Integration Creator makes defining actions and resources effortless by parsing OpenAPI schemas.
Action Types allow for flexible API call definitions, while Resource Types standardize data formats.
Modified at 2024-11-29 20:30:04
