> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SaaS App Developer Guide

> An end-to-end walkthrough for building apps with the DingTalk (YiDA) Cool SaaS Factory. It covers prerequisites for low-code SaaS app development, how to access the SaaS development workbench, the scope of aPaaS platform capabilities, main app design, Cool App design, and how to release and publish your app.

📎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

<Steps>
  <Step title="Step 1">
    Apply for DingTalk product service provider qualification.
  </Step>

  <Step title="Step 2">
    Review the full contents of the [DingTalk Open Platform ISV Help Center](https://alidocs.dingtalk.com/i/p/KrwmPQ5g4OEAG79n/docs/3KLw95QMzkb8gGOpYEk78AjrymPeEN2q?dontjump=true).
  </Step>

  <Step title="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](https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2/docs/7Y36k14mK9AV35vAPyg185NqapjblR2D).
  </Step>
</Steps>

### 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.

1. 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.

2. 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Click Create Version and fill in the SaaS app version information, including version number and release notes." />
</Steps>

### 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."<br />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.<br />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

1. 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.

1. 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<br />Read access to Contacts department users<br />Access to query industry Contacts information<br />Read access to user information |
| To-Do tasks             | Write access to To-Do items in the To-Do app<br />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<br />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<br />Write access to organization storage files<br />Read access to organization storage files                                             |

(Figure 1: Permission configuration screen)

(Figure 2: Grant permission notice screen)

2. 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

1. 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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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}](https://www.yidaapps.com/saasAppCallback/\\\{appKey})), where appKey is the YiDA app code, such as "APP\_XXX."

2. 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.

<Steps>
  <Step title="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>

  <Step title="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.
  </Step>
</Steps>

#### 4.3.1 Trial Testing the Main App

<Steps>
  <Step title="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.
  </Step>

  <Step title="Once you have access to the app management backend, review the backend configuration of the subscribed SaaS app. Specific features can be modified." />
</Steps>

**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:
>
> 1. 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.
> 2. 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.
> 3. 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.
> 4. The version scope above includes all business rules and formulas within the version.

3. 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="After filling in the information, click Save and publish to generate the coolappcode." />

  <Step title="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." />
</Steps>

## 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:

1. By default, upgrade options are the latest iterations released after the currently published version.
2. 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

<AccordionGroup>
  <Accordion id="q1" title="Q1: How do I modify form fields in a subscribed SaaS app?">
    A: Modifications to features such as forms are already supported.
  </Accordion>

  <Accordion id="q2" title="Q2: Can I delete components from a published form?">
    A: Deleting components from published standard or workflow forms — including subforms — is not allowed.
  </Accordion>

  <Accordion id="q3" title="Q3: Can a published custom page carry a fixed CorpId?">
    A: No custom link may carry a fixed CorpId.
  </Accordion>

  <Accordion id="q4" title="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.
  </Accordion>

  <Accordion id="q5" title="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."
  </Accordion>

  <Accordion id="q6" title="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.
  </Accordion>
</AccordionGroup>