The Maestrano integration contains 3 aspects: Single Sign-On, Billing and Connec! Data-sharing. Here is the list of tasks to perform during the integration in order to be listed on the Maestrano platform.
Workflows to be supported with the data-sharing will be agreed with Maestrano as documentation will be required to explain end-users how the integration works.
1 - Single Sign On
1.1 Metadata endpoint
1.1.1 Expose metadata endpoint REQUIRED
The application metadata endpoint is publicly available for Maestrano. See Metadata Endpoint
1.2 Initial Single Sign On
1.2.1 Company creation REQUIRED
Given a new user triggers the SSO and the group_id does not match any existing Company, a new Company is created using the Company name and group_id reference
1.2.2 User creation with known Company REQUIRED
Given a new user triggers the SSO and the group_id matches a Company group_id, a User is created using the first name, last name and user_id reference and is associated to the existing Company
1.2.3 User creation with unknown Company REQUIRED
Given a new user triggers the SSO and the group_id does not match any Company group_id, a Company is created as per Company creation and a User is created using the first name, last name and user_id reference and is associated to the created Company
1.3 Subsequent Single Sign On
1.3.1 User with user_id matching an existing account REQUIRED
Given an existing user triggers the SSO and the user_id is know, the User is authenticated and logged into its account
1.4 User migration
1.4.1 User email matching - Applicable if user email is unique IF APPLICABLE
Given a new user triggers the SSO and the user_id is not known but the user email is, the user_id is linked to the user record. This means the User is already existing in your system and has subscribed to Maestrano service in order to link his account.
2 - Account management and Billing
2.1 Service subscription
See Billing Management for more information
2.1.1 Set up application billing on account creation REQUIRED
Given a new account is created as per Company creation, and the user selects a pricing plan, the billing should be set up as per your T&Cs
If you propose a free trial, the billing should not occur before the end of the trial period
2.1.2 Send ad-hoc bills OPTIONAL
Given the customer triggers extra charges using the application (in-app purchases, send SMS, etc...), an ad-hoc bill is sent to Maestrano
Only applicable if your application proposes services with extra cost out of the Maestrano sharing-revenue agreement
2.2 Subscription cancellation notification
2.2.1 Cancel subscription or access on group cancellation notification REQUIRED
Given a cancellation notification is sent to the Group Webhook, the subscription to your service should be cancelled as per your T&Cs.
Note that you can put in place some mechanism to contact the users to reconnect your service or use it out of the Maestrano context. In this case you will need to handle the billing directly with the customer.
2.2.1 Cancel user access on user cancellation notification IF APPLICABLE
Given a cancellation notification is sent to the Group User Webhook, the user access should be blocked if applicable.
This applies if the application pricing is based on the number of users, in this case as a user has been removed from the system, pricing should be updated accordingly
3 - Connec! data-sharing
3.1 Initial Import
3.1.1 Import data upon initial single sign-on REQUIRED
Given a new Company is created with a specified group_id on initial SSO (see Company creation), the relevant data are imported from Connec! for this group_id
3.2 Push entities to Connec!
The term entities refers to the resources exposed by Connec! data-model. This can be customers, products, invoices, employees, etc...
3.2.1 Send created records to Connec! REQUIRED
When a record is created in the application, a request to create an entity is sent to Connec! The ID of the Connec! entity is stored to support subsequent updates (see Multi-Tenant Integration)
3.2.2 Send updated records to Connec! REQUIRED
When a record is updated in the application, a request to update the entity is sent to Connec! The ID of the Connec! entity is specified as the one retrieved from a previous entity creation. Failing to specify such ID would result in creating a duplicate record
3.3 Receive notifications from Connec!
See Connec! Webhook
3.3.1 Notification of a new entity REQUIRED
When a notification is received from Connec! and the ID of the entity is not known, a new record is created in the application and the ID of the Connec! entity is stored to support subsequent updates
3.3.2 Notification of an updated entity REQUIRED
When a notification is received from Connec! and the ID of the entity is known, the matching record is updated in the application
4 - Multi-tenant integration
See How does the Multi-Tenant Integration work?