Edit integration

Through the integration settings, you can configure product, user, and access management integration with the AppDirect platform. For each product, there is an Edit Integration page. Use it to configure integration for a product the first time, and to edit the settings thereafter.

From the Edit Integration page, you can take these actions:

• Enter the integration endpoint URLs to which the AppDirect platform will send your server notifications of key events related to your product. For example, subscription creations, subscription changes, and access management events.
• Create a custom form to collect information from users as they complete the checkout flow for your product.
• Enable notifications to you before the end of a customer's subscription billing period, so you know the deadline for reporting metered usage, if applicable.
• Define the information that Company Administrators must enter when they create new users for, or assign new users to, the application.
• View, and renew at any time, the system-generated OAuth Consumer Key and Secret for use with secure API calls.
• Enable Domain management, and add the integration endpoint URLs to which the AppDirect platform will send notifications when a domain is linked, or unlinked, from a product. It will also get and verify domain settings when a domain is purchased on the marketplace, alone or with a product.

After you, the application Developer, integrate your product with AppDirect, AppDirect notifies you of your customers’ subscription and access management events. These events occur when customers take actions in AppDirect that affect the status of their accounts, or subscriptions, related to your application. For example, when customers create, change, or cancel subscriptions.

When these events occur, AppDirect sends notifications to the endpoint URLs that you configure (they must be non-interactive endpoints). It calls the endpoint URL that you host, and passes a URL to it, as a parameter, which you use to fetch information about the event. Then, you can adjust the user's license accordingly.

We recommend that you use HTTPS endpoint URLs secured with SSL certificates. The SSL certificates must be valid and verifiable by the AppDirect server, and therefore signed by a well-known certificate authority such as VeriSign, GeoTrust, Comodo, DigiCert, Thawte, GoDaddy, or Network Solutions.

Before you configure endpoints

To avoid common integration issues:

• AppDirect calls your notification URLs with an HTTP GET request.
• Each configured URL must include the eventUrl query parameter placeholder so AppDirect can pass the event location at runtime.
• Your service must read eventUrl and send an HTTP GET request to that URL to fetch the full event payload.
• If eventUrl is not present in the URL you configure, AppDirect will not include an event URL in the request sent to your server, and your integration will not be able to fetch the event details.
• Use the configured integration security credentials to validate and fetch events. For details, see Validate outbound event notifications.
• Keep the original AppDirect request open while your service fetches and processes the event so you can return the final result in the same transaction.
• Live integration tests can execute real subscription flows. Plan test data, downstream side effects, and cleanup (for example, canceling test subscriptions) before running them.

Basic synchronous event flow

Configure integration endpoints

1. Go to Manage > Billing and Distribution > Products > productName | Edit. The product dashboard page opens.
2. On the left menu, click Integration | Edit Integration. The Edit Integration page opens.
3. Under Subscriptions, enter the integration endpoint URL that you host for each subscription event.

   • Each URL must include eventUrl as a query parameter placeholder (for example, https://isvapp.com/create?eventUrl={eventUrl}).

   • At runtime, AppDirect replaces the placeholder with the event URL.

   • For details, see The eventUrl parameter and Integration events.

   • Use the following URL patterns:

     Correct

     • https://isvapp.com/create?eventUrl={eventUrl}
     • https://isvapp.com/subscription/create?source=appdirect&eventUrl={eventUrl}

     Incorrect

     • https://isvapp.com/create (missing eventUrl)
     • https://isvapp.com/create?eventURL= (missing {eventUrl} template token)
     • https://isvapp.com/create?eventUrl= (empty value, missing {eventUrl} template token)

Trigger for AppDirect to call this URL	Event
Subscription purchase	SUBSCRIPTION_ORDER
Subscription upgrade or downgrade	SUBSCRIPTION_CHANGE
Subscription cancellation	SUBSCRIPTION_CANCEL
Subscription status change (for example, when subscriptions are suspended after a free trial expires or automatically canceled for non-payment) Important: We strongly recommend that you configure this integration endpoint to get notifications when a subscription is activated, deactivated, and closed.	SUBSCRIPTION_NOTICE
The company or user information is modified.	USER_UPDATED

4. To make your Subscription Create Notification, Subscription Change Notification, and Subscription Cancel URLs interactive endpoints, select This is an interactive endpoint. For more information, see Interactive endpoints.
   Note: We recommend that you do not use interactive endpoints, because if there are problems with the final redirection from the vendor site to the marketplace, checkout can fail. If you need to collect additional information during checkout, see Add required information.
5. (Optional) Configure a custom form to collect information from users when they subscribe to this product.
6. (Optional) To enable an automatic notification in advance of the end of a customer's subscription billing period, select Subscriptions | Enable upcoming invoice notification. This can be useful when you need to calculate and submit usage before the platform generates the customer's invoice.
7. (Optional) To allow marketplace customers to purchase multiple subscriptions of this product, select Subscriptions | Allow multiple subscriptions purchased per company. This setting only appears for products of the Cloud Infrastructure and Services product type.
8. Under Add-Ons | Add-On Notification URL, enter the integration endpoint URL. This setting only appears for products of the Cloud Infrastructure and Services product type.
   • AppDirect calls this URL for all events related to add-ons (add-on order, change, cancel, bind, and unbind events).
   • This URL can only be non-interactive.
   • This URL must contain the eventUrl parameter, which is replaced by the URL of the order when the event occurs.
9. Under Access Management, enter the integration endpoint URLs. The URLs must include the eventUrl parameter placeholder, which is replaced by the URL of the relevant event at runtime.

Trigger for AppDirect to call this URL	Event
User assignment	USER_ASSIGNMENT
User unassignment	USER_UNASSIGNMENT

10. Under User Information to Sync, select each data type that you want Company Administrators to enter when they assign users to the application.
11. (Optional) Under Restriction Management, enter the Restriction URL. This is the URL that the marketplace calls to check if there are restrictions for the purchase or upgrade of this product. For example, http://<your-service-url>/api/v1/restrictions.

note

Restriction URL is only supported in checkout V1. The marketplace sends a request to the URL with details such as editionInfo, userInfo, operation, and companyUUID. The platform responds with a list of restrictions, which the marketplace uses to enforce constraints.

12. (Optional) Click the toggle to enable or disable Domain management. When enabled, a customer must purchase a domain, or add a domain that they already own, when they purchase this product. If you use a Plaza theme, this option must be enabled in the theme before it can be used (Configure domain cross-selling).
13. In Maximum Number of Associated Domains, select a value. This value is the maximum number of domains that can be associated with this product subscription purchase.
14. Enter the integration endpoint URLs that you host for each domain management endpoint. The URLs must contain the correct placeholders. See the following table.

Trigger	Trigger for AppDirect to call this URL	Placeholders
Link Notification	A user tries to link a domain to this product.	customerIdentifier domainName
Unlink Notification	A user tries to unlink a domain from this product.	customerIdentifier domainName
Get Domain Settings	The AppDirect platform wants to get domain settings for this product.	customerIdentifier domainName
Verify Domain Settings	The AppDirect platform wants to verify that the domain was set up correctly for this product.	customerIdentifier domain callbackUrl

15. Click Save. A confirmation dialog opens and prompts you to copy the OAuth consumer key and OAuth consumer secret to a secure location, because they are no longer visible after you confirm.