Description of Calling APIs Related to Scheduled Tasks 

Version

The following table lists the latest version compatibility requirements for FineDataLink and related plugins.

Note:

You can log in to the FineDataLink project and choose System Management > Registration Management to view the platform module version on the Version Information tab page.

Application Scenario

You want to trigger or execute scheduled tasks on demand to improve data timeliness and accuracy. Specific scenarios include:

• After business personnel submit data using a FineReport data entry report, the data will be processed by a scheduled task in FineDataLink to generate results. Business personnel expect to see the updated data promptly.

• Business personnel want to see real-time data on reports or have a button to trigger data updates manually.

• You expect FineDataLink tasks to be triggered immediately upon the completion of certain actions in the self-developed or third-party business systems of the enterprise to ensure data timeliness.

• After business personnel submit data in Jiandaoyun, the data will be processed or synchronized by a scheduled task in FineDataLink. Business personnel expect to see the updated data promptly.

Function Description

You can use the Open Platform - FineDataLink API plugin, which provides FineDataLink-related APIs to implement scheduled task triggering/execution on demand.

Note:

For details about APIs in FineDataLink that support invocation, see Introduction to APIs Related to Scheduled Task.

Plugin Installation

Note:

Contact technical support personnel to obtain the Open Platform - FineDataLink API plugin and the FineDataLink API Forwarding_EK plugin. You can search and download the Open Platform plugin in Plugin Management on the platform.

Calling APIs in FineReport

To call APIs related to scheduled tasks in a FineReport template:

If FineReport and FineDataLink are deployed independently in different domains, the following operations must be performed sequentially: Install the Open Platform plugin in FineDataLink, followed by the Open Platform - FineDataLink API plugin, and then install the FineDataLink API Forwarding_EK plugin in FineReport.

For details about plugin installation steps, see Plugin Management.

For details about usage examples, see Examples of Calling Scheduled Task APIs in FineReport Templates.

Note:

You must disable the Open Platform - FineDataLink API plugin before updating the Open Platform plugin.

Others

When calling APIs in Jiaodaoyun or other external systems, install the Open Platform plugin and the Open Platform - FineDataLink API plugin sequentially in the FineDataLink project.

Plugin Registration

You need to register the plugin. For details about specific steps, see Plugin Registration.

Introduction to Pages After Successful Plugin Installation

Task ID

After successful plugin installation, the task ID of scheduled tasks in Data Development will be displayed, which can be copied, as shown in the following figure.

Instance ID

Choose O&M Center > Scheduled Task > Running Record. You can view the record ID (the instance ID) and copy it by clicking the copy icon that appears when you hover the cursor over the record ID, as shown in the following figure.

API Management

Choose System Management > Open Platform > API Management. The following figure shows the page.

APIs on the FineDataLink Extension API and the FineDataLink Extension API (Platform Login Authentication) tab pages are the same, differing only in the API-calling paths.

You need not be particularly concerned about these two tabs, as the authentication and usage steps for APIs are already explained in this document. For details, see the "API Authentication Method Explanation" chapter.

• FineDataLink Extension API: Available authentication methods include SM2 Signature Authentication, AK/SK Direct Authentication, and Digest Signature Authentication. For details about usage, see the "Built-in Authentication Methods of Open Platform" section of this document.

• FineDataLink Extension API (Platform Login Authentication): This API uses platform login authentication (fine_auth_token). The usage is explained in the "fine_auth_token Authentication" section of this document.

API-triggered tasks are defined as manually triggered tasks. The operating user assigned to these tasks is determined by the authentication method used.

Built-in Authentication Methods of Open Platform

Description

Note:

These authentication methods apply to independently deployed projects. You are advised to use AK/SK Direct Authentication or Digest Signature Authentication.

1. The plugin includes three alternative authentication methods. You can also add authentication methods as needed. If authentication is performed using the client_id and secret parameters provided by Open Platform, operations on the API will be considered to be performed by the super administrator. For details, see Open Platform Plugin.

2. You can manage the API authentication logic under Open Platform > Application Management. For details, see Open Platform Plugin. For example, if you select AK/SK Authentication Method, the client_id and secret parameters must be passed in the request. For details about usage examples, see Examples of Calling Scheduled Task APIs in FineReport Templates.

3. After you authenticate APIs using the built-in methods, operations on the API will be considered to be performed by the super administrator.

4. If a different operating user is required, you can add the decUser parameter (to specify the username or the user ID) to either the header or the query.

Example One: AK/SK Direct Authentication

This example demonstrates how to call the Run a Task by Task ID API in Postman.

1. Log in to the FineDataLink project, choose System Management > Open Platform > Application Management, click Add to create an application, and set Alternative Authentication to AK/SK Direct Authentication, as shown in the following figure.

Note:

You are advised to use AK/SK Direct Authentication or Digest Signature Authentication if FineReport and FineDataLink projects are deployed independently.

2. Click the  icon on the right side of the created application, and remember the values of Application ID and Secret Key, as shown in the following figure.

3. Choose Permission Management > API. This step illustrates how to assign permission on the above-mentioned new application for the Run a Task by Task ID API, as shown in the following figure.

4. Add the client_id and secret parameters. The final API is:

http://IP address:Port number/webroot/decision/sp/client/api/fdl/workId/execute?client_id=Application ID&secret=Secret key

Note:

If all parameters in the API request body are optional and you want to set the body content to empty, input {} in the body.

The result is shown in the following figure.

Example Two: Digest Signature Authentication

This example demonstrates how to call the Run a Task by Task ID API in Postman.

For details about digest signature authentication, see the "Built-in Alternative Authentication Method" section of Open Platform Plugin.

1. Log in to the FineDataLink project, choose System Management > Open Platform > Application Management, click Add to create an application, and set Alternative Authentication to Digest Signature Authentication, as shown in the following figure.

Note:

You are advised to use AK/SK Direct Authentication or Digest Signature Authentication if FineReport and FineDataLink projects are deployed independently.

2. Click the  icon on the right side of the created application, and remember the values of Application ID and Secret Key, as shown in the following figure.

3. Choose Permission Management > API. This step illustrates how to assign permission on the above-mentioned new application for the Run a Task by Task ID API, as shown in the following figure.

4. Digest signature authentication requires two parameters:

• client_id=Application ID

• _sign_=Digest algorithm(Concatenated string of Application ID, Secret key, and Timestamp) suffixed by Timestamp (in milliseconds).

You can use a digest algorithm (such as SM3, MD5, or SHA256) to sign the concatenated string of Application ID, Secret Key, and Timestamp.

The example in this section uses MD5 as the digest algorithm. Set method to MD5 and timeout to 300 (unit: second), as shown in the following figure.

If you choose another algorithm, modify the method value accordingly.

The process involves encrypting the concatenated string of Application ID, Secret key, and Timestamp using the MD5 algorithm. The timestamp represents the current time, and the API call must be made within the period defined by Timestamp + Value of timeout.

For example,  _sign_ = Digest algorithm(Concatenated string of Application ID, Secret key, and Timestamp) suffixed by Timestamp (in milliseconds) = MD5(03eff5c6a0c04f53bcb842d3d9d4e58646925d8209104b1f839857c01b6bcf181760584080000) suffixed by 1760584080000=2cebacb26626565d15797b22c0044b6f1760584080000

The MD5 result is a 32-character value.

Note:

You can use online encryption tools.

5. Add client_id and _sign_ parameters. The final API is http://IP address:Port number/webroot/decision/sp/client/api/fdl/workId/execute?client_id=03eff5c6a0c04f53bcb842d3d9d4e586&_sign_=2cebacb26626565d15797b22c0044b6f1760584080000.

Note:

1. Fill in the actual values of _sign_.

2. If all parameters in the API request body are optional and you want to set the body content to empty, input {} in the body.

The result is shown in the following figure.

fine_auth_token Authentication

Note:

This applies to integrated deployment environments and utilizes the built-in login authentication mechanism of the product.

Description

If you use the fine_auth_token authentication method (the same method used by the platform), operations will be considered to be performed by the user associated with the generated token. For details, see Open Platform Sub-plugin.

1. When the request URL includes module/ (for example, changing /sp/client/api/* to /sp/client/api/module/*), the API authentication logic is no longer managed under Open Platform > Application Management. Instead, a valid FanRuan authentication token (fine_auth_token value) must be included in the request. Authentication will fail if the token is missing or invalid.

2. If you use this authentication method, operations on the API will be considered to be performed by the user mapped from the fine_auth_token value, and the user cannot be modified via the decUser parameter.

Example

This example demonstrates how to call the Run a Task by Task ID API in Postman.

1. Prepare the request URL.

The endpoint for the Run a Task by Task ID API is http://IP address:Port number/webroot/decision/sp/client/api/fdl/workId/execute. To use the fine_auth_token authentication method, you need to add module/ to the URL:

http://IP address:Port number/webroot/decision/sp/client/api/module/fdl/workId/execute

2. Obtain the fine_auth_token value.

Log in to FineDataLink, open the browser's developer tools (press F12), navigate to the Network tab page, select any request, and check its Headers section to find the value of fine_auth_token, as shown in the following figure. Log in to FineDataLink, open the browser's developer tools (press F12), navigate to the Network tab page, select any request, and check its Headers section to find the value of fine_auth_token, as shown in the following figure.

Note:

The fine_auth_token value obtained via the method shown in the following figure has a validity period. Alternatively, you can call Frontend SSO Interface (where the accessToken value in the API response is the fine_auth_token value) to fetch the most up-to-date value of fine_auth_token for each request.

3. The configuration in Postman is shown in the following figure.

Note:

If all parameters in the API request body are optional and you want to set the body content to empty, input {} in the body.

The result is shown in the following figure.

For an example of how to call scheduled task APIs in FineReport templates, see Examples of Calling Scheduled Task APIs in FineReport Templates.

In FineReport, you can call an API by adding JavaScript code to the report template.

The JavaScript code for scheduled task invocation in this chapter applies to scenarios where FineReport and FineDataLink are deployed independently.

POST Request

The following is an example of JS code, which calls the Query the Instance List by Task ID API.

FR.GetWorkRecordsByWorkId(
    {
        workId: "e10f1f1a-d567-4058-98bb-b71204154f8b",
        latest: false,
        startTime: "",
        finishTime: "",
        taskStatus: "SUCCESS",
        triggerMethod: "MANUAL",
    },
    function (error, response) {
        if (error) {
            console.error("Request failed:" + error);
        } else {
            console.log("The request was successful, and the response data is:" + JSON.stringify(response));
        }
    }
);

When calling different APIs using JavaScript, the modifications required for the example JS code are explained below:

Note:

The content in the green section in the following figure represents the body parameters or the query parameters in the scheduled task API to be called, where values of the query parameters must be enclosed in double quotes (""), for example, "01 Data Synchronization". Separate the green section from the purple section by a comma (,). Keep the content in the purple section unchanged across calls to different scheduled task APIs.

GET Request

The following is an example of JS code, which calls the Query Instance Information by Instance ID API.

FR.GetRecordInfoByRecordId(
    "3c73b3a0-30ba-4044-984e-6b61e5c3b638",
    function (error, response) {
        if (error) {
            console.error("Request failed:" + error);
        } else {
            console.log("The request was successful, and the response data is:" + JSON.stringify(response));
        }
    }
);