Onboarding Apps and Solutions
Onboarding of an app or solution enables developers to upload AAA permission files for individual apps or all apps within a solution to all tenants or a selected list of tenants in a stack.
The onboarding process should be repeated whenever there are changes in permissions files associated with apps. This ensures the latest permissions for an app are updated within AAA, which is essential for secure usage of apps and solutions.
There are two types of tenants:
- Development Type Tenant: This pertains to tenants that are based out of a Sandbox stack or any other development or staging environment. Developers must upload their permissions file to the development type tenant in order test their app within the development environment.
- Production Type Tenant: Production type tenants are designed for customer subscription and usage, for example, Shared Stack has tenants that are of production type. Developers should onboard their permissions file in production-type tenant only after thorough testing of their apps and solutions. There are role level restrictions allowing only dev-admins and product admins the authority to onboard apps or solutions to production-type tenants.
Gating policies ensure that only valid apps and solutions are onboarded to production tenant environments, preventing issues for end users.
The key gating policies are:
- State-based Gating: Only applications and solutions in a "LIVE" state can be onboarded to production tenants, ensuring work-in-progress apps or solutions are not propagated to end users. Additionally, a solution can only be made LIVE if all apps within the solution are LIVE. Attempting to onboard non-LIVE apps/solutions to production tenants will trigger actionable errors to prevent access, warning developers to transition their apps/solutions to LIVE.
- Role-based Gating: Publishing an app or solution for customer usage is restricted to product admins. Onboarding apps or solutions and updating permission files are restricted to app owners only. This prevents unauthorized access changes by tying permissions to owners.
- Ownership-based Gating: Only app developers who belong to the app's organization can upload AAA permission files. If a non-owner attempts to upload an app they don't own, they will not be able to proceed. This prevents incompatible permission files from being overwritten and causing app failure.
These gaiting policies only apply to production type tenants onboarding and use the new onboarding API. The legacy API still allows onboarding apps in any state, but it is scheduled for deprecation.
Onboarding an app to a prod-type tenant involves the following steps:
- Onboard App: Developers can choose whether to onboard to select tenants using solution/listing details, or simplify the process by onboarding to a whole stack at once. The data parameter included in the response should be used to obtain the status.
- Automatic Subscription Update: Subscription is updated automatically after onboarding is completed. During onboarding, both Production and Developer tenants' subscriptions are automatically updated to use the latest app version.
- App Approval: Use UpdateAppStates to ensure all your apps which are a part of a solution are LIVE by passing them through all lifecycle states.
- Solution Approval: Use UpdateSolutionStates to ensure your solution’s TECH_REVIEW has been approved.
- Onboard Solution: Developers can choose whether to onboard to select tenants using solution/listing details, or simplify the process by onboarding to a whole stack at once. Both options enable tenant subscriptions upon successful onboarding. The data parameter included in the response should be used to obtain the status.
- Automatic Subscription Update: Subscription is updated automatically after onboarding is completed. During onboarding, both Production and Developer tenants' subscriptions are automatically updated to use the latest app version.
The onboarding APIs supports bulk onboarding of an app or solution to all tenants in stack. This feature increases developer efficiency by reducing repetitive tasks of onboarding an app or solution to all tenants in stack using a single API call.
Onboard to All Tenants in Stack
Instead of specifying individual tenant IDs, developers can provide the stackId` parameter to onboard an app/solution to all tenants within a particular stack. This handles iterating through all tenants automatically.
Benefits:
- Easily onboard to many related tenants
- Avoid repeatedly calling API individually per tenant
- Scale to future tenants added to the stack
Setting the stackCredentialOverwrite flag to PRODUCTION forces the use of production credentials even when onboarding to developer/staging tenants.
Benefits:
- Safely test production-style onboarding in staging
- Simulate production permissions and governance pre-deployment
Developers have the option to choose from two different APIs for app and solution onboarding. These APIs are designed to assist you in onboarding an app or solution to a development or production type tenant. Additionally, you can use them to onboard your app or solution to a stack of tenants, a list of tenants, or a single tenant. When it comes to generating the initialization sequence, you have two options. You can use V2 API to automatically generate the init sequence by using the app-permissions file you uploaded. Alternatively, you can use V1 API to manually specify the init sequence. We highly recommend using V2 API as it not only saves you time but also helps avoid human errors related to sequencing.
- POST /developer/tenants/v2/onboarding: Use this API to onboard a solution to the provided list of tenants without manually providing the init sequence. The API determines the init sequence based on the app-permissions file uploaded. Please note that the API will ignore the manually provided init sequence .
- POST /developer/tenants/onboarding: Use this API to onboard an app or solution when you provide the init sequence manually.
When performing a GET status request, developers can see when the init sequence logs. Status will be started or completed .
Path Parameters
Parameter | Description |
|---|---|
stackCredentialOverwrite | Forces the use of production credentials even when onboarding to developer/staging tenants. The acceptable value is production. |
Body Parameters
Parameters | Description |
|---|---|
versionId* | The unique ID for the app or solution version. Example: appversion:0f77dbcd-56vtb-5e12-90d8-6990e3a82b |
tenantIds | Unique Id for the tenant to onboard. |
stackId | Onboard app or solution version to all tenants for a stackId. Acceptable Values:
|
Example Requests:
The following example request shows:
- Onboarding an App
- Onboarding a Solution
- Onboarding an App/Solution with a stackId
Response:
On success, the response returns 200 for app onboarding and 202 for solution onboarding.