1 Documentation Guide

The Custom Connector is designed for integrating ShareCRM with other SaaS or private systems that provide APIs, such as customer-developed systems or other SaaS platforms. Once connected, users can automatically synchronize business documents between both systems without manually entering data or verifying accuracy in each system.

This document includes step-by-step instructions for setting up a Custom Connector and troubleshooting common issues. It is intended for implementation consultants, technical advisors, sales managers, CSMs, and other relevant personnel.

2 Custom Connector Implementation & Configuration

2.1 Prerequisites

Before implementation, ensure the customer’s tenant environment is activated and the Custom Connector product has been purchased (verify that the order is active!).

2.2 Implementation Configuration

2.2.1 Connection Setup

Create a new connector, select Custom Connector as the type, and fill in the connector details:

picture coming soon:

Result Format Instructions:
If the return value is in JSON format, specify:
- error code field as code
- error msg field as message
- data field as data
- Success code as 0

json { "code": "0", "message": "Success", "data": { ... } }

Header Script Instructions:
There are two ways to add headers to requests. If both are configured, the Headers parameter takes precedence!

1. Headers Parameter Configuration: Supports placeholders (currently limited to enterpriseId and pushToken).
   picture coming soon:
   picture coming soon:

2. Custom APL Function: Example:
   code return ["token":"test123", "tenantId":context.tenantId]

2.2.2 API Configuration

Configure the object structure and fields based on the customer’s API documentation. After setup, verify the request and response interfaces under API Configuration. Use Postman to test the request path and template, comparing the response with the expected protocol.

picture coming soon:
picture coming soon:

2.2.3 API Adaptation

Use API functions to implement CRUD operations. If the tenant’s service protocol is incompatible with the standard connector, customize functions to transform requests/responses. Below are templates for common operations:

picture coming soon:

Note: After creating a function, configure the parameter:
- Type: Map
- Name: syncArg

picture coming soon:

API Function Return Value Structure:
picture coming soon:

2.2.3.1 Create

objectData Parameters:

API Function Example:
```code /** * Connector Object API - Create * Replace todo sections with custom logic. * Set parameter: Map type syncArg. **/ String errorCodeKey = “code” // Error code field (must match connector config) String successCode = “0” // Success code (must match connector config) String errorMessageKey = “message” // Error message field String dataKey = “data” // Data field String dataIdKey = “masterDataId” // Primary Object ID field String detailDataIdsKey = “detailDataIds” // Sub-object IDs field

Map objectData = syncArg[“objectData”] as Map def apiName = objectData[“objAPIName”] // ERP object API name (e.g., BD_MATERIAL) def masterData = objectData[“masterFieldVal”] // Primary Object data Map<String, List<Map<String, Object»> detailMap = objectData[“detailFieldVals”] as Map

// todo: Implement creation logic Map<String, String> headers = [“token”: “xxxxxx”] def url = “http://xxx/xxx/create” Map<String, Object> arg = [“objAPIName”: apiName, “masterData”: masterData, “detailMap”: detailMap] def (Boolean error, HttpResult httpResult, String msg) = http.post(url, headers, arg) if (error) { log.info(“ERP object creation error: “ + msg) Map<String, Object> result = [:] result[errorCodeKey] = “500” result[errorMessageKey] = msg return result } log.info(“ERP object created. URL:” + url + “ Args:” + arg + “ Response:” + httpResult) Map createDataResult = httpResult.content as Map

// todo: Build response String masterDataId = createDataResult[“data”][“masterDataId”] Map<String, List> detailIdsMap = createDataResult["data"]["detailDataIds"] as Map

Map<String, Object> data = [:] data[dataIdKey] = masterDataId data[detailDataIdsKey] = detailIdsMap

Map<String, Object> result = [:] result[errorCodeKey] = successCode result[errorMessageKey] = “” result[dataKey] = data return result ```

(Similar detailed examples follow for Edit, Batch Query, Single Query, Invalidate, Re-enable, Invalidate Sub-object, and Event Subscription—omitted for brevity.)

2.3 Proxy Service Support (Optional)

If the tenant lacks external network access, use the proxy service (code attached).

Configuration:
1. Modify application.properties to set the token for authentication.
2. Add X-fs-erpdss-token to the connection header.

picture coming soon:
picture coming soon:

Implement RouterAdaptController:
- create: Create in ERP
- update: Update in ERP
- invalid: Invalidate Primary Object
- queryMasterBatch: Fetch incremental ERP data for sync
- queryMasterById: Fetch single ERP record by ID

3 FAQ

Under construction…

Attachment:
erpdss-template-stdapi.zip (315.0 KB)