SaaS App Developer Guide

📎627 DingTalk (YiDA) Cool SaaS Factory app developer guide outline.pdf

1 End-To-End Process for Low-Code SaaS App Development

See Partnership process guide - Open Platform.

1.1 Prerequisites

Step 1

Apply for DingTalk product service provider qualification.

Step 2

Review the full contents of the DingTalk Open Platform ISV Help Center.

Step 3

A SaaS app must take the form of a Cool App. For guidance on how to convert your app, see Low-code Cool App design guide for DingTalk.

1.2 How to Access the SaaS Development Workbench

Once your organization holds product solution provider verification, sign in to YiDA. The entry point “Enter SaaS development workbench” appears in the top menu for direct access. From the SaaS app workbench, you can create SaaS apps.

1.3 Supported aPaaS Platform Capabilities

The DingTalk SaaS Factory development workbench mirrors the existing YiDA interaction model. This release provides the following core capabilities:

Platform capabilities:

Note: Extended enhancements such as custom connectors, data preparation, DataV dashboards, and custom components are not yet supported. They will be added in future iterations.

2 Main App Design

Once the prerequisites are complete, you can start building your SaaS app. If you already have a complete solution under another YiDA organization and want to switch it directly to SaaS mode, contact the YiDA product and engineering team to request migration to the SaaS environment.

Using the SaaS development workbench and the capabilities currently provided by the platform, design your app to match your business requirements. For example:

The development flow for these capabilities is identical to YiDA’s in-house app development. Contact the YiDA team if you run into issues.

If your SaaS product ships with baseline business data and you want subscribers to see sample data after subscribing, enter this “baseline data” and maintain it in a single folder named “Baseline business data” (see the example below).

3 Cool App Design

From the SaaS development workbench, you can configure Cool App card styles and the logic for sending and updating cards under the app layer: Card Management / Integration & Automation flow. See the following document for detailed design guidance:

4 App Release

Step 1

Once both the main app and the Cool App are built, go to the “Release & publish” screen and create a new version for SaaS app functional testing. After testing passes, submit the app for publication.

Click Create Version and fill in the SaaS app version information, including version number and release notes.

4.1 App Version Management

Whenever app functionality changes, you can create a new version. New versions default to the “Unpublished” state. Click Publish to release the version.

4.2 App Publication Request — Link a Third-Party App

Step 1: Link a Third-Party App

SaaS development workbench	DingTalk Open Platform > Third-party enterprise app
1. After creating at least one app version, submit the publication request under “Publish to DingTalk App Center.” 2. Select the third-party app that you registered on the Open Platform and link it here.	1. On the DingTalk Open Platform, under Third-party enterprise app, create an H5 Micro app and fill in the basic app information. 2. Generate the app credential.

Step 2: Fill in SaaS App Development Information

Copy the SaaS app URL and configure the app information.

SaaS development workbench	DingTalk Open Platform > Third-party enterprise app
1. After completing Step 1, click Copy and paste the link into the Open Platform, as shown on the right.	1. On the DingTalk Open Platform, under Third-party enterprise app, select the registered third-party app, click “Development Management,” and fill in:

Step 3: Verify SaaS App Configuration Items

(1) Confirm app development information

On the DingTalk Open Platform, under Third-party enterprise app, select the registered third-party app and confirm that all functional configuration items are complete. Finish any that are still missing.

(2) Manage permissions

To safeguard SaaS product data, apps must confirm authorization scopes with users at activation. ISVs must configure the required permission scopes themselves.

Open the “Manage permissions” menu. Standard SaaS products must select the following permissions, then click “Batch apply.”

Permission category	Permission scope
Card	Write access to interactive card instances
Personal permissions	Read access to Contacts profile
Contacts management	Read access to Contacts department information Read access to Contacts department users Access to query industry Contacts information Read access to user information
To-Do tasks	Write access to To-Do items in the To-Do app Read access to To-Do items in the To-Do app
App authorization	Permissions required to call ISV-exclusive APIs
Authentication	Access to the silent login API for the enterprise Micro app backend
Scene groups	Management access to chat-related APIs Read access to chat-related APIs
YiDA	Select all
Bots	Permission for internal bots to send messages within your organization
Storage	Read access to organization storage space Write access to organization storage files Read access to organization storage files

(Figure 1: Permission configuration screen) (Figure 2: Grant permission notice screen)

If your SaaS product uses the “DingTalk Official” connector under “Integration & Automation > Connector node,” contact the YiDA team to confirm which first-party connector permissions you need to select.

Partial mapping of connectors to permissions:

Connector	Permission category	Permission scope
Smart meeting room	Smart meeting room	Write access to meetings in the Video Meeting app
Project management	Project management	Write access to tasks in the Project app

Step 4: Self-Service Request to Skip the Security Self-Check

To skip the self-check, configure “Events & callbacks” as follows:

Step 1: For the encryption Aes_key, encrypt YiDA’s systemToken with the decrypt method below and use the result.

private static final char[] HEX_ARRAY = "0123456789abcdef".toCharArray();

public static String bytesToHex(byte[] bytes) {
        char[] hexChars = new char[bytes.length * 2];
        for (int i = 0; i < bytes.length; i++) {
            int v = bytes[i] & 0xFF;
            hexChars[i * 2] = HEX_ARRAY[v >>> 4];
            hexChars[i * 2 + 1] = HEX_ARRAY[v & 0x0F];
        }
        return new String(hexChars);
    }

private static String decrypt(String input) throws NoSuchAlgorithmException {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
        // Convert the hash into a 43-character encrypted string
        return bytesToHex(hash).substring(0, 43);
}

Retrieve YiDA’s systemToken from YiDA app Settings > Deployment & Operations. Step 2: The signature Token is the YiDA systemToken above. Step 3: Callback request URL (https://www.yidaapps.com/saasAppCallback/\{appKey}), where appKey is the YiDA app code, such as “APP_XXX.”

Complete the app self-check “Security review” content. For security admission evaluation, see 📎YiDA Cool SaaS security admission guide - ISV.pdf.

4.3 Trial Organization Management

Use trial organization management for ISV self-testing of both the main app and the Cool App in either published or unpublished states. After self-testing passes, submit the app for publication to the DingTalk App Center and the Cool App Marketplace.

Step 1

Select the SaaS app version, click “Trial organization management,” and choose a trial organization. If none exists, click “Create” to open the Open Platform and create one.

Step 2

Once the trial organization is created, link and authorize the app version you want to test. After authorization succeeds, the app appears under Workbench > Ungrouped in that trial organization.

4.3.1 Trial Testing the Main App

Step 1

Open the app from the workbench. If the trial tester is not the “Contacts admin” or the “app Super Admin,” ask the organization admin or app admin to grant access to the app backend.

Once you have access to the app management backend, review the backend configuration of the subscribed SaaS app. Specific features can be modified.

The following features can all be modified:

General logic: Once a modification is made and the ISV later releases a new version, the customer’s local configuration takes precedence for the affected feature. Changes to the main app do not sync down to the child app. If no modification was made, incremental resource changes in the main app sync to the child app. Approval process change logic:

If the child app subscribes to V0 and the main app has an unpublished V1, V1 does not appear in the child app’s version history.

If the child app subscribes to V0 without customization and the main app later upgrades to V1, the child app continues to display and run against the subscribed V0.

If the child app subscribes to V0 and customizes it, an internal V0 history version is created together with a V1 draft. After the child app subscribes to the new version, the current process no longer follows main app upgrades.

The version scope above includes all business rules and formulas within the version.

By default, the “Baseline business data” form data from the main app is carried over to the child app so baseline data works out of the box. Modifications are supported.

4.3.2 Trial Testing the Cool App

Step 1

After the main app passes testing, test the Cool App. First, submit the Cool App information. Click “Publish to DingTalk Cool App Marketplace > Submit publication request” and fill in the Cool App publication information, including basic details, access entry points (up to 3), open method, and bot information.

After filling in the information, click Save and publish to generate the coolappcode.

Copy the coolappcode of this Cool App, create an internal group in the current trial organization, and install and test it on mobile as shown below.

5 App Operations

5.1 Version Upgrades

After the ISV-built SaaS app is published to the App Marketplace and customers subscribe, ISVs can iterate on features and, under “YiDA SaaS development workbench > App settings > Remote operations,” roll out version upgrades to specific organizations individually or in batches. Feature notes:

By default, upgrade options are the latest iterations released after the currently published version.
Batch version upgrades across multiple paying organizations are supported.

Remote operations — coming soon.

5.2 App Activation Authorization Landing Page

Once a YiDA SaaS app is published to the DingTalk Open Platform and App Center, you can customize the authorization landing page. 👉Learn more Configuration notes:

Upload the PC and mobile authorization landing pages separately (only one image per channel is supported).
After uploading, copy the “Trial access URL” and go to Partner Self-Operation Platform > Third-party enterprise app > Product publication management > App details > Manage > “In-app authorization settings.” Once integration is complete and your self-acceptance passes (👉 learn more about the acceptance process), the SaaS app can be promoted across more DingTalk online channels, such as DingTalk Search.

Mobile view	PC view

6 FAQ

Q1: How do I modify form fields in a subscribed SaaS app?

A: Modifications to features such as forms are already supported.

Q2: Can I delete components from a published form?

A: Deleting components from published standard or workflow forms — including subforms — is not allowed.

Q3: Can a published custom page carry a fixed CorpId?

A: No custom link may carry a fixed CorpId.

Q4: What should I do if Cool App installation fails?

A: Test the Cool App by installing it in a new internal group in an organization other than the main app’s organization.

Q5: When a custom page redirects to a form page, how do I pass the current group ID?

See the “Cool App FAQ and typical scenario design guide.”

Q6: How do I hide the menu and navigation bar on a SaaS app page?

A: When a YiDA page is embedded in another system, you can hide both the top navigation bar and the left-side page function navigation bar. Append ?isRenderNav=false to the embedded page URL.

Getting Started

Quick Start

Form Management

Workflow Design

Report Design

Aggregate Table Design

Portal Design

Custom Pages

Integration & Automation

Cool App

App Management

Platform Management

Internationalization

YiDA Dedicated

Developer Features

1 End-To-End Process for Low-Code SaaS App Development

1.1 Prerequisites

1.2 How to Access the SaaS Development Workbench

1.3 Supported aPaaS Platform Capabilities

2 Main App Design

3 Cool App Design

4 App Release

4.1 App Version Management

4.2 App Publication Request — Link a Third-Party App

Step 1: Link a Third-Party App

Step 2: Fill in SaaS App Development Information

Step 3: Verify SaaS App Configuration Items

(1) Confirm app development information

(2) Manage permissions

Step 4: Self-Service Request to Skip the Security Self-Check

4.3 Trial Organization Management

4.3.1 Trial Testing the Main App

4.3.2 Trial Testing the Cool App

5 App Operations

5.1 Version Upgrades

5.2 App Activation Authorization Landing Page

6 FAQ

​1 End-To-End Process for Low-Code SaaS App Development

​1.1 Prerequisites

​1.2 How to Access the SaaS Development Workbench

​1.3 Supported aPaaS Platform Capabilities

​2 Main App Design

​3 Cool App Design

​4 App Release

​4.1 App Version Management

​4.2 App Publication Request — Link a Third-Party App

​Step 1: Link a Third-Party App

​Step 2: Fill in SaaS App Development Information

​Step 3: Verify SaaS App Configuration Items

(1) Confirm app development information

(2) Manage permissions

​Step 4: Self-Service Request to Skip the Security Self-Check

​4.3 Trial Organization Management

​4.3.1 Trial Testing the Main App

​4.3.2 Trial Testing the Cool App

​5 App Operations

​5.1 Version Upgrades

​5.2 App Activation Authorization Landing Page

​6 FAQ

1 End-To-End Process for Low-Code SaaS App Development

1.1 Prerequisites

1.2 How to Access the SaaS Development Workbench

1.3 Supported aPaaS Platform Capabilities

2 Main App Design

3 Cool App Design

4 App Release

4.1 App Version Management

4.2 App Publication Request — Link a Third-Party App

Step 1: Link a Third-Party App

Step 2: Fill in SaaS App Development Information

Step 3: Verify SaaS App Configuration Items

Step 4: Self-Service Request to Skip the Security Self-Check

4.3 Trial Organization Management

4.3.1 Trial Testing the Main App

4.3.2 Trial Testing the Cool App

5 App Operations

5.1 Version Upgrades

5.2 App Activation Authorization Landing Page

6 FAQ