Tasks for a consumer:¶
AIP exposes the following API endpoints for consumer tasks.
Base URLs: Environments
If the ERP is integrated with Aptean IAM using client credentials, request header must contain the bearer token from IAM authentication.
Authorization: bearer token
Refer to AIP Swagger for full API documentation (based on environment).
| Task | API |
|---|---|
| Create service for webhook | see sample service |
| Register a consumer | POST /v2/consumers |
| Create data mapper | Optionally, go to Data Mapper |
| Log processing steps | POST /v2/events/eventlog |
| Delete a consumer | DELETE /v2/consumers/{id:guid} |
| Republish consumer event | POST /v2/events/republish |
Create service for webhook¶
See the following api controller template to build a webhook service. Webhook template
Webhook service must perform the following actions: - Respond to validation event so AIP can send events to the webhook - this action is called only when the consumer is registered the first time - Handle events and acknowledge with HTTP response code 200 - See the sample project for how to implement payload signature verification You must have access to Aptean GitHub Enterprise. - Send request to /events/eventlog to log all pertinent actions associated with processing the event - these logs are used for event visualization and are critical for troubleshooting integration issues, if any.
Register a Consumer¶
Refer to Product-level Integration create a product-level consumer when you're working with multi-tenant SaaS products.
Event from another product or service is consumed for a specific customer. In AIP, every integration is identified by a unique consumer ID, and it needs to be created only once per event type. For example, customer A wants to integrate Product M with Ship for event type erp-order-created-v1 (refer to Event Definition example), the following request should be sent.
The example uses the curl syntax - convert to the structure of any HTTP client used in your programming language. The example is for tenant-level consumer. Please refer to Product-level Integration for other examples.
curl --location 'https://appcentral-aip-dev.apteansharedservices.com/v2/consumers' --header 'Authorization: bearer' --header 'Content-Type: application/json' --data-raw '
{
"contactEmail": "aptean@test.com",
"sourceTenantId": "fe117256-e78f-45f0-b1b5-46164fd049c0",
"sourceProductId": "8AF17029-C37D-4945-AC5F-88D72651FC9B",
"targetProductId": "06870F46-B961-44AA-98E6-FBEE0EB69BCA",
"targetSchema": "",
"subscribedEvents": [
{
"eventDefinitionType": "erp-order-created-v1",
"webhook": "https://your-webhook",
"ttl": "00:10:00",
"attempts": 5
}
]
}'
Note that ttl and attempts are now managed by AIP itself and not by consumer.
If you want to use Data Mapper to map data from source to the schema suitable for your product, you can specify the target schema when registering customer. Target schema is defined as Event Definition under your product - see Publisher topic for how to create event definitions. Provide this event definition type in the "targetSchema" property when registering consumers.
See following page for additional configuration element: Configuration
The response of consumer creates a request that returns unique consumerId value. This ID is necessary if your application needs to use polling to retrieve the events. This could be the case if your application is deployed on-prem and not able to expose a public endpoint for webhook or requires authentication to connect.
After executing the create request, run the query using the consumer ID to verify the status of the webhook validation. It should be Active to indicate that the consumer created successfully. Otherwise, it will return the reason for failure.
Sample query using the consumer ID from the response of the create request:
curl --location 'https://appcentral-aip-dev.apteansharedservices.com/v2/consumers/819ffbaa-4c0e-4a32-9c56-7b3053fac7f1' --header 'Authorization: bearer'
Next: Event Log