Chapter 9 Portal Integration

Overview: Portal Integration

Portal integration refers to configuring data source connections from external systems for portal components. Currently, three connection methods are supported:

• Internal Connection

Component data sources from this system and EasyCraft business modules.
Supports direct synchronization through internal interfaces.

• Third-Party Connection

Supports manual integration of third-party systems.
Requires developing custom component data sources, then uploading them to the EasyCraft platform.

• Platform Integration

Supports adding new platform-integrated systems.
Configuration is done through the interface by selecting integrated platform interface data sources.

9.1 Discovering This System

Internal Connection: System Discovery and Synchronization

By discovering systems, synchronize portal component data sources from this system and the EasyCraft business modules as follows:

In Portal Management > Portal Integration, execute "Search current system" to synchronize portal component data sources from all business modules into the portal integration module, as shown:
Click Logs to view successful or failed synchronization records for this system.
Click System Details to view all synchronized portal component data sources from this system.

9.2 Integrated System Connection Configuration

Third-Party Integration via the Integration Platform

The EasyCraft Digital Work Platform's portal management also supports configuring third-party data source connections through integrated platform registration interfaces.

To integrate third-party interfaces, refer to the configuration guide in:

Integration Platform > Integration Scenarios > Portal Integration

Steps to Create Integrated Component Data Sources

Login to the EasyCraft Digital Work Platform.
Navigate to: Portal Management > Portal Integration, then click "New System" in the connected systems list.
On the Create New System page:
- Select the integrated system type.
- The address and system number will be auto-filled.
- Click Confirm.
The new system appears in the system list. Click on it to access Data Source Details.
Click the New button to create a new component data source.
Select a data source interface created by the Integration Platform.
Configure parameters and click Save.

Parameter Configuration Guide

Basic Parameters

Field	Description
Data Name	Customizable name for the component data source.
Module	Select or add the business module it belongs to.
Data Format	Format supported by the interface; determined during interface creation.
Allow Anonymous Access	If disabled (default), requires login. If enabled, allows access without login.
Accessible Users	Leave empty for all users. Set specific users to restrict access.

Input Parameters

Value Method	Description
Fixed Value	Enter static content based on parameter type (e.g., user ID, phone).
User-defined	Parameter left blank; configured during portal usage.
Use Component Parameter	Fill in a component parameter (e.g., `starttime`, `endtime`).
From Cookie	Pull value from a browser cookie (e.g., `LtpaToken`, `X-AUTH-TOKEN`).
From Header	Pull value from HTTP header (e.g., `Content-Type`).
Null Value	Leave the parameter without a value.

Button Configuration

You can configure buttons that appear on the portal component:

Add: Add new content.
More: View more data.
Custom: Custom button with your specified name and action.

Final Steps

When configuring the portal:
- Select: Business Component > Integrated System > Integrated Component Data Source
Preview the integrated component data source on the portal.

9.3.1 Third-party system access configuration

Configuring a Third-Party System in EasyCraft Portal

Follow these steps to integrate a third-party system into the EasyCraft portal:

1. Create a New System

Navigate to Portal Backend Management.
Select Portal Management > Portal Integration.
Click "New System".

2. Fill in System Data

Enter the name and domain of the third-party system (without a trailing slash /).
Optionally, add a system description.
Click Confirm.

3. Configure Data Source

Click System Details.
Download the template provided.
Follow the "Data Source File Content Configuration Guide" to fill in the required information.
Package the files and import them into the system.

Tip:
Enable the SSO (Single Sign-On) function and configure the identifier parameter.
This ensures that when clicking this data source in the portal, the identifier will redirect the user to the third-party page — achieving single sign-on capability.

4. Portal Configuration

While configuring the portal, navigate to:
- Business Component > Third-Party System > Select Module Component Data Source.

5. Preview

Preview the custom component data source to ensure it functions correctly in the portal.

9.3.2.1 Documentation

Third-Party System Data Source Configuration Notes

When uploading third-party system data sources to the EasyCraft platform, please note the following:

Limitations

Multilingual Recognition is not currently supported for third-party system uploads.

Multilingual Identifier Format

For fields such as names and prompts, use the following syntax:

{module.name}
{sys-demo:module.name}

API Request URL Guidelines

If using a relative address, it must start with /.

Calendar Component Parameter Format

When integrating calendar components, use the following dynamic timestamp variables:

Start Time: !{startTime}
End Time: !{endTime}

These values are passed as timestamps.

URL Parameter Escaping

When passing multiple parameters in a URL, do not use & directly, as it may cause errors.

Use the HTML escape sequence: &

Example:

url="sys://user/sys-notify/sysNotifyProcess?fdId=!{fdId}&amp;fdType=!{fdType}"

# 9.3.2.2 JSON Data Structure Explanation

| Field   | Name              | Required | Remarks                                 |
|---------|-------------------|----------|-----------------------------------------|
| success | Whether successful| Yes      | true for success, false for failure     |
| code    | Error code        | Yes      |                                         |
| msg     | Error message     | Yes      |                                         |
| data    | Return data       | No       |                                         |


# 9.3.2.3 Common code list

| Code value         | Code description   |
|--------------------|--------------------|
| return.optSuccess  | Operation successful |
| return.optFailure  | Operation failed     |
| status.401         | Not logged in        |
| status.403         | No permission        |


# 9.3.2.4 &lt;modules&gt; Used to add modules (required)

```xml
<modules>    
    <module id="sys-portal-component" name="{sys-portal:systemComponentModule.name}"/>
</modules>

Field	Name	Required	Remarks
id	Unique identifier	Yes	Use letters and symbols; Rules: Module name words or letters
name	Name	Yes

9.3.2.5 <source> is used to add data sources (Required)

<source 
    id="ds.sys-portal.link.plaintText" 
    name="{sys-portal:sysPortalLink.plaintText}"  
    format="data.link"         
    anonymous="false" 
    moduleId="sys-portal" 
    desc="Shortcut - Plain Text Type">
    ...
</source>

Field Description

Field	Name	Required	Remarks
id	Unique identifier	Yes	Combine letters and data
name	Name	Yes
format	Data format	Yes	Please refer to the front-end data format list
anonymous	Whether anonymous	Yes	Yes: true; No: false
moduleId	Module ID	Yes
desc	Data source description	No
thumbnail	Thumbnail	No	Third-party upload not supported

Child Element Configuration Items

Request configuration: Required
Parameter configuration: Optional
Operation item configuration: Optional
Default display information: Required
Extended configuration items: Optional

9.3.2.6 <request> is used to add request information (Required)

<source id="ds.sys-portal.link.plaintText" name="{sys-portal:sysPortalLink.plaintText}" format="data.link" anonymous="false" moduleId="sys-portal" desc="Shortcut - Plain Text Type">
    ...
</source>

Field Description

Field	Name	Required	Remarks
id	Unique identifier	Yes	Combine letters and data
name	Name	Yes
format	Data format	Yes	Please refer to the front-end data format list
anonymous	Whether anonymous	Yes	Yes: true; No: false
moduleId	Module ID	Yes
desc	Data source description	No
thumbnail	Thumbnail	No	Third-party upload not supported

Child Element Configuration Items

Request configuration: Required
Parameter configuration: Optional
Operation item configuration: Optional
Default display information: Required
Extended configuration items: Optional

9.3.2.7 <config> Used to add request parameters

Data Source Configuration Item

<configs>    
  <config 
    name="Shortcut" 
    key="fdId" 
    type="list" 
    required="true" 
    default="1hj2h314jhhj41jh412h4" 
    placeholder="Please select a shortcut..."
  >        
    <content>
      <![CDATA[
        {
          "url": "/data/sys-portal/sysPortalLink/listPortlet",
          "method": "post",
          "data": {
            "conditions": {
              "fdType": {
                "$eq": 10
              }
            }
          },
          "model": "com.easycraft.sys.portal.core.entity.content.SysPortalLink"
        }
      ]]>
    </content>
    <enableWhen></enableWhen>
  </config>
</configs>


| Field         | Name           | Required | Remarks                                                                     |
| ------------- | -------------- | -------- | --------------------------------------------------------------------------- |
| `name`        | Name           | Yes      |                                                                             |
| `key`         | Parameter key  | Yes      | Placeholder for data and param parameters in request config, e.g. `!{fdId}` |
| `type`        | Parameter type | Yes      | Refer to parameter type description                                         |
| `required`    | Required       | Yes      |                                                                             |
| `default`     | Default value  | No       | Multiple values separated by `,` or `;`                                     |
| `placeholder` | Prompt message | No       | Prompt message when inputting or selecting                                  |
| `content`     | Extended field | No       | Different types have different content configurations                       |
| `enableWhen`  | Sample data    | No       | Usage scenario, e.g.: `{key:xxx, value:ooo}`                                |
| `help`        | Auxiliary info | No       | Hover tooltip appears near the control marked with `?`                      |
| `prefix`      | Prefix         | No       | Text displayed before the parameter input box                               |
| `suffix`      | Suffix         | No       | Text displayed after the parameter input box                                |



## 9.3.2.8 &lt;operation&gt; Used to add component buttons: e.g., More, Add
```xml

<operations>    
    <operation name="{button.more}" href="/km/review/index.jsp" mobileHref="/km/review/mobile" type="more" target="_blank"> 
    </operation>
</operations>

Built-in Syntax href and mobileHref support the following configuration methods (where sys:// is replaced by the current system's base URL: href="sys://user/sys-notify/sysNotifyProcess"

Button URL with Parameters href="sys://user/sys-notify/sysNotifyProcess?fdId=!{fdId}&fdType=!{fdType}"

Field	Name	Required	Remarks
`name`	Name	Yes
`href`	PC link	Yes
`mobileHref`	Mobile link	No	If not available, redirect to `href`
`type`	Operation method	Yes	Add: `create`, More: `more`
`target`	Link Method	Yes	Default is `_blank`; Options: `_blank`, `_self`, `_parent`, `_top`

`<renders>` Configuration

<renders>    
  {
    "desktop": "@elements/link-text",
    "mobile": "@elements/link-text"
  }
</renders>

Specify the Default Rendering for the Data Source:
Single value can be specified as:

{
  "desktop": "@elements/link-text",
  "mobile": "@elements/link-text1"
}

| Field   | Name                         | Required | Remarks                                                  |
| ------- | ---------------------------- | -------- | -------------------------------------------------------- |
| desktop | Default rendering for PC     | Yes      | Refer to the frontend rendering list for rendering names |
| mobile  | Default rendering for mobile | Yes      |                                                          |

# 9.3.2.10 &lt;extendConfig&gt; Used for adding extensions

```xml
{"realTimePush",true}

Field	Name	Required	Remarks
desktop	Default rendering for PC	Yes	Refer to the frontend rendering list for rendering names
mobile	Default rendering for mobile	Yes

9.3.2.11 Detailed introduction of <config> parameter types

Note: The following content corresponds to the <content> within the <config> tag

{ "min": 1, "max": 5, "format": "URL" }

Field	Name	Required	Remarks
min	Minimum length	No
max	Maximum length	No
format	String format	No	Optional: URL (link), EMAIL (email), CNID (ID number), IPv4, TEL

{    "min" : 1,    "max" : 100,    "step":1,    "numberType" : "number"}

Field	Name	Required	Remarks
min	Minimum	No
max	Maximum	No
step	Step size	No	Click
numberType	Number type	No	Optional values: number, integer, float

• Page display size type=rowsize This configuration is for input box settings

 Row number type, no extended attributes
{ }

• Enumeration type type=enum

{    "options" : [{        "label" : "Current month",        "value" : "month"    },{        "label" : "Current week",        "value" : "week"    }],    "showType": "radio",    "multi":false}

Field	Name	Required	Remarks
showType	Enumeration display method	Yes	Available: radio, select, checkbox
multi	Multiple selection allowed	Yes	Default false; checkbox defaults to true
options	Enumeration list	Yes
label	Display name	Yes
value	Actual value	Yes

Tree type type=tree For tree-type interfaces, it is necessary to support querying the subordinate list by the parent ID. The corresponding subordinate categories are then queried and displayed:

{            "url":"/data/sys-common/treexml",            "params":{               "s_bean":"kmCoprojectCategoryTreeService",               "parentId":"!{parentId}",               "nodeType":"!{nodeType}"            },            "canSelectCategory":true,           "idProperty":"value",           "nameProperty":"text",           "sysID":"",            "detailsUrl":"/data/sys-person/sysPersonPortlet/details?fdId=!{fdId}",           "displayProperty":"fdName"          }

Field Description Built-in parameter description:

!{fdId} and !{parentId} both obtain unique values through the value set by the property field idProperty, and the two field values are the same;

!{fdId} represents the placeholder for the detail value.

!{parentId} represents the placeholder for the parent ID.

!{nodeType} represents the placeholder for the node type (CATEGORY, TEMPLATE).

The tree-type interface returns information in XML or JSON as follows:

Field	Name	Required	Remarks
url	Request URL	Yes
method	Request method	Yes	POST not supported
params	Request parameters	No	Used for GET requests
canSelectCategory	Whether category selectable	Yes	true: leaf only; false: all
dataType	Data return format	Yes	XML or JSON
idProperty	ID attribute	No	Defaults to 'value'
nameProperty	Name attribute	No	Defaults to 'text'
sysID	System ID	No
detailsUrl	Detail interface	Yes	GET format with JSON
displayProperty	Display property	Yes	Maps to nameProperty of data detail interface

Configuration Options

Property	Description	Required	Notes
`canSelectCategory`	Whether category can be selected	Yes	`true`: only leaf nodes (nodes without children) can be selected; `false`: all can be selected
`dataType`	Data return format	Yes	Supports XML format, JSON format
`idProperty`	ID attribute	No	Defaults to the `value` field in returned data; uses fields in returned data as `!{fdId}`, `!{parentId}`
`nameProperty`	Name attribute	No	Defaults to the text field from returned data; displays the field from the data format
`sysID`	System ID	No	Used when working with a system different from the current data source

Detailed Interface Configurations

Details must be in GET request format with JSON.

Property	Description	Required	Notes
`detailsUrl`	Data detail interface	Yes	Used during editing; requires displaying the display name corresponding to the type ID
`displayProperty`	Display property	Yes	Corresponds to the name attribute of the data detail interface; defaults to the data dictionary's `displayProperty`

Public Configurations (EASYCRAFT Digital Work Platform)

Property	Description	Required	Notes
`model`	Entity name	No	For built-in system use; third parties cannot use
`detailsUrl`	Data detail interface	No	Can configure: `/data/sys-portal/info?fdId=!{fdId}&model=?`

API Configuration & Data Formats

Example Response Formats

XML Example

<RestResponse>
    <success>true</success>
    <data>
        <text>Company News</text>
        <value>15c1a1c78aabf1bc4ac4af04ea8999f9</value>
        <nodeType>CATEGORY</nodeType>
        <url>/data/origin-ekp/xxxx</url>
    </data>
    <data>
        <text>Company News</text>
        <value>15c1a1c78aabf1bc4ac4af04ea8999f9</value>
        <nodeType>CATEGORY</nodeType>
        <url>/data/origin-ekp/xxxx</url>
    </data>
    <msg/>
    <code/>
</RestResponse>

JSON Example

{
  "success": true,
  "data": [
    {
      "text": "Company News 1",
      "value": "15c1a1c78aabf1bc4ac4af04ea8999f9",
      "nodeType": "CATEGORY"
    },
    {
      "text": "Company News 2",
      "value": "15c1a1c78aabf1bc4ac4af04ea8999f8",
      "nodeType": "CATEGORY"
    }
  ],
  "msg": "",
  "code": ""
}

List Type Configuration (type="list")

{
  "url": "/data/sys-portal/sysPortalLink/listPortlet",
  "method": "post",
  "data": {
    "offset": "!{offset}",
    "pageSize": "!{pageSize}",
    "conditions": {
      "fdName": {
        "$contains": "!{searchWord}"
      }
    }
  },
  "dataType": "json",
  "idProperty": "fdId",
  "nameProperty": "fdName",
  "multi": true,
  "detailsUrl": "/data/sys-portal/info?model=com.easycraft.sys.portal.core.entity.content.SysPortalLink&fdId=!{fdId}",
  "displayProperty": "fdName"
}

Field	Name	Required	Remarks
`url`	Request URL	Yes	The interface return data format
`method`	Request method	Yes	POST or GET
`data`	Request params	Yes	Contains pagination & filters
Offset	Custom parameter	Yes	Calculated as page number × items per page
Items per page	Custom parameter	Yes	Fixed parameter placeholder
`dataType`	Data return format	Yes	XML or JSON
`idProperty`	ID attribute	Yes	Uses fields in returned data (`!{fdId}`, `!{parentId}`)
`nameProperty`	Name attribute	Yes	Uses display fields from data
`multi`	Multiple selection	Yes	`true` = allowed, `false` = not allowed
`sysID`	System ID	No	For use with other systems
`detailsUrl`	Data detail interface	Yes	Must be a GET request with JSON
`displayProperty`	Display property	Yes	Defaults to data dictionary `displayProperty`
`model`	Entity name	No	Only for built-in systems

{
  "success": true,
  "msg": "",
  "code": "",
  "data": {
    "page": {
      "pageSize": 0,
      "offset": 0,
      "totalSize": 100
    },
    "columns": [
      {
        "property": "string",
        "title": "string"
      }
    ],
    "data": [
      {
        "href": "string",
        "cells": [
          {
            "col": "string",
            "value": "string"
          }
        ]
      }
    ]
  }
}

Return Field Description

Field	Name	Required	Remarks
`success`	Success flag	Yes	`true` = success, `false` = failure
`code`	Error code	Yes	Error identifier
`msg`	Error message	Yes	Description of error
`data`	Return data	No	Response payload

Tree/List Information (JSON)

{
  "success": true,
  "data": [
    {
      "fdId": "abadf2231",
      "value": "15c1a1c78aabf1bc4ac4af04ea8999f9"
    }
  ],
  "msg": "",
  "code": ""
}

9.3.3.1 Interface Provision

Portal Module Extension Point

To allow the portal module to know which modules have configured data sources,
the corresponding extension points need to be implemented by this module.

Extension Point

package com.easycraft.sys.portal.annotation;

@PorletPoint(sysCode="ekp-cloud")

The entity service corresponding to the data source needs to implement the interface com.easycraft.sys.portal.api.IPortletApi to obtain data details during editing.

9.3.3.2 Interface Modification

Data Source XML Configuration

The interface and data format configured in the data source XML file must correspond.

Fields in the actual response can be more than defined, but must not be fewer.

Example Configuration

<source id="ds.sys-portal.link.plaintText" format="data.link" ...>
    <request 
        method="POST" 
        dataType="json" 
        url="/data/sys-portal/sysPortalLink/portlet" 
        contentType="application/json">
        ...
    </request>
    ...
</source>

Interface Response Format

The return data of the interface /data/sys-portal/sysPortalLink/portlet must conform to the agreed standard format.
The data field must match the expected data.link format.

Example Response

{
  "success": true,
  "code": "return.optSuccess",
  "msg": "Your operation was successful!",
  "data": [
    {
      "text": "Baidu",
      "href": "http://www.baidu.com",
      "target": "_blank"
    },
    {
      "text": "Google",
      "href": "https://www.google.com",
      "target": "_blank"
    }
  ]
}

Standard Response Structure

{
  "success": true,             // Whether the request was successful
  "code": "return.optSuccess", // Status code
  "msg": "Your operation was successful!", // Return message
  "data": ...                  // Return data
}

Field	Description	Required
`text`	Display text for the link	Yes
`href`	Target URL	Yes
`target`	Link target (`_blank`, `_self`)	No (defaults to `_self`)

9.4 Integrated System Permission Configuration

Portal Permission Configuration

1. Portal Integrated System Permission Configuration

Supports configurable Maintainers and Users.

Maintainers

If empty: Only administrators can maintain by default.
If set: Both maintainers and administrators can:
- Add system data sources
- Configure settings
- Delete system data sources
Note: New integrated system users are automatically added to the maintainers list.

Users

If empty: All users can use the system components by default.
If set: Only the configured users and maintainers can select the integrated system data source during portal configuration.

2. Integrated Component Data Source Permission Configuration

Supports configurable Users and Non-users.

Users

If empty: All system users can use it by default.
If set: Only the specified component users can configure and use the component data source.

Non-users

If empty: User permissions take precedence.
If set: Non-user permissions override user permissions.
- If there is overlap between users and non-users, non-user permissions prevail.

3. Batch Permission Setting

Supports selecting multiple components for batch configuration of component data source permissions.

⚠️ Important Note:
When batch setting permissions:

If no authorized and unauthorized users are configured,
Clicking OK is equivalent to secondary authorization.
Please operate carefully to avoid overwriting the first authorization configuration.

Overview: Portal Integration

• Internal Connection​

• Third-Party Connection​

• Platform Integration​

9.1 Discovering This System

Internal Connection: System Discovery and Synchronization​

9.2 Integrated System Connection Configuration

Third-Party Integration via the Integration Platform​

Steps to Create Integrated Component Data Sources​

Parameter Configuration Guide​

Basic Parameters​

Input Parameters​

Button Configuration​

Final Steps​

9.3.1 Third-party system access configuration

Configuring a Third-Party System in EasyCraft Portal​

1. Create a New System​

2. Fill in System Data​

3. Configure Data Source​

4. Portal Configuration​

5. Preview​

9.3.2.1 Documentation

Third-Party System Data Source Configuration Notes​

Limitations​

Multilingual Identifier Format​

API Request URL Guidelines​

Calendar Component Parameter Format​

URL Parameter Escaping​

9.3.2.5 <source> is used to add data sources (Required)

Field Description​

Child Element Configuration Items​

9.3.2.6 <request> is used to add request information (Required)

Field Description​

Child Element Configuration Items​

9.3.2.7 <config> Used to add request parameters

Data Source Configuration Item​

<renders> Configuration​

9.3.2.11 Detailed introduction of <config> parameter types

Configuration Options​

Detailed Interface Configurations​

Public Configurations (EASYCRAFT Digital Work Platform)​

API Configuration & Data Formats

Example Response Formats​

XML Example​

9.3.3.1 Interface Provision

Portal Module Extension Point

Extension Point​

9.3.3.2 Interface Modification

Data Source XML Configuration

Example Configuration​

Interface Response Format

Example Response​

9.4 Integrated System Permission Configuration

Portal Permission Configuration

1. Portal Integrated System Permission Configuration​

Maintainers​

Users​

2. Integrated Component Data Source Permission Configuration​

Users​

Non-users​

3. Batch Permission Setting​

• Internal Connection

• Third-Party Connection

• Platform Integration

Internal Connection: System Discovery and Synchronization

Third-Party Integration via the Integration Platform

Steps to Create Integrated Component Data Sources

Parameter Configuration Guide

Basic Parameters

Input Parameters

Button Configuration

Final Steps

Configuring a Third-Party System in EasyCraft Portal

1. Create a New System

2. Fill in System Data

3. Configure Data Source

4. Portal Configuration

5. Preview

Third-Party System Data Source Configuration Notes

Limitations

Multilingual Identifier Format

API Request URL Guidelines

Calendar Component Parameter Format

URL Parameter Escaping

Field Description

Child Element Configuration Items

Field Description

Child Element Configuration Items

Data Source Configuration Item

`<renders>` Configuration

Configuration Options

Detailed Interface Configurations

Public Configurations (EASYCRAFT Digital Work Platform)

Example Response Formats

XML Example

Extension Point

Example Configuration

Example Response

1. Portal Integrated System Permission Configuration

Maintainers

Users

2. Integrated Component Data Source Permission Configuration

Users

Non-users

3. Batch Permission Setting