ScriptCallActivity

Category: Common Steps Namespace: CMS.Plugin.FlowManagement.Domain.FlowBusiness.Activitys Base Class: ActionActivity Module: FlowManagement.Domain

Overview

ScriptCallActivity (Automation Script) is a node used to call scripts defined in the base script management within the process. It inherits from ActionActivity and supports calling pre-configured automation scripts in the system, writing the script execution status code to the process context. This node supports synchronous and asynchronous call modes, allowing flexible execution of various automation tasks.

ScriptCallActivity is an important component of process automation, enabling the execution of complex business logic, data processing, system integration tasks, etc., without writing code directly in the process nodes.

Business Scenarios

Applicable Scenarios

• Data Processing: Execute complex data transformation, calculation, validation, etc.
• System Integration: Call external system interfaces or execute system commands.
• Business Logic: Execute complex business rules and judgment logic.
• Batch Operations: Execute batch data processing or file operations.
• Scheduled Tasks: Cooperate with timing triggers to execute periodic tasks.

Role in the System

ScriptCallActivity plays the role of a script executor in the LMES process system:

• Calls scripts configured in the base script management.
• Supports synchronous and asynchronous execution modes.
• Handles script execution results and exceptions.
• Writes execution status to the process context.

Collaboration with Other Nodes

• BusinessActivity: Prepares parameters before script invocation and processes results after invocation.
• ActionActivity: As an action node, execution timing can be configured.
• ApiCallActivity: Can work with API calls to implement complex integration scenarios.
• PythonScriptActivity: If inline scripts are needed, use the Python Script node.

Configuration Description

Basic Configuration

Property Name	Type	Required	Default	Description
ScriptId	string	Yes	-	Associated script, calls the script defined in base script management
Wait	bool	No	true	Whether to wait for execution to end
Authorization	string	No	-	Authorization information (Request Token)
Action	ActionType	No	Execute	Execution timing (Inherited from ActionActivity)
IsSynchronous	bool	No	true	Whether to execute synchronously (Inherited from ActionActivity)

Configuration Details

ScriptId

Description: The ID of the associated script, specifying the script to be called. The script must be pre-configured in the base script management module.

Value Range: String, corresponding to the script name or ID configured in script management.

Notes:

• Ensure the specified script exists in the system.
• The script must be enabled and configured correctly.
• The script content will be retrieved via API and executed.

Wait

Description: Whether to wait for the script execution to complete. When set to true, the process waits for the script to finish; when set to false, the process continues immediately without waiting.

Value Range: true or false

Notes:

• Wait=true (Default): Suitable for scenarios where script execution completion must be ensured.
• Wait=false: Suitable for scenarios where only triggering the script is needed, and the result is not immediately required.
• Asynchronous execution (Wait=false) can improve process execution efficiency.

Authorization

Description: Authorization information used for authentication of the script execution request. Usually a Bearer Token or other authentication token.

Value Range: String, format depends on the system's authentication method.

Notes:

• If script execution requires authentication, correct authorization information must be provided.
• Can be dynamically obtained from the process context.

Process Context

Input Parameters

Parameter Name	Type	Description
ScriptId	string	Script ID can be dynamically obtained from process context
Authorization	string	Authorization info can be dynamically obtained from process context

Output Parameters

Parameter Name	Type	Description
{NodeName}_StatusCode	int	Response status code after script execution

Data Flow Description

1. Before Execution:

   • Initialize status code to 200 (OK).
   • Get IInternalApi service.
   • Get script content via ScriptId.

2. Script Execution:

   • Call IInternalApi.ExecutScriptsAsync to execute the script.
   • Pass script content, wait flag, and authorization info.

3. After Execution:

   • Write HTTP status code to {NodeName}_StatusCode (NodeName is the value of the node's Name property).
   • Record execution logs.

Business Logic Description

Processing Flow

The execution flow of ScriptCallActivity is as follows:

1. Initialization:

   • Set default status code to 200 (OK).
   • Get IInternalApi service.

2. Get Script:

   • Call internalApi.GetScriptsByNameAsync(ScriptId) to get script information.
   • If script does not exist, record warning log and return.

3. Execute Script:

   • Record execution parameter logs.
   • Call internalApi.ExecutScriptsAsync to execute the script.
   • Pass script content, Wait flag, ScriptId, and Authorization.

4. Exception Handling:

   • Catch HttpRequestException.
   • Handle ApiResponseStatusException.
   • Record error logs and status codes.

5. Completion:

   • Record final status code log.

Dependent Services

Service Interface	Usage	Description
IInternalApi	Script Execution Service	Responsible for retrieving script content and executing scripts
IJsonSerializer	JSON Serialization	Parsing error responses
Flow.ServiceProvider	Service Provider	Getting dependency injected services
Flow.Logger	Logger	Recording script execution logs

Exception Handling

Exception Type	Handling Method	Description
HttpRequestException	Record error log, set status code	HTTP request failed
ApiResponseStatusException	Parse error message, record log, set status code	API returned error status code

Logging

ScriptCallActivity records the following key logs:

• Script Not Found: ScriptId={ScriptId} does not exist!
• Before Execution: ScriptId={ScriptId}, Wait={Wait}
• After Execution: ScriptId={ScriptId}, StatusCode={StatusCode}
• Exception: Complete error message

Usage Examples

Basic Example

{
  "Type": "ScriptCallActivity",
  "Name": "Execute Data Processing Script",
  "Alias": "DataProcessScript",
  "ScriptId": "DataProcessing",
  "Wait": true
}

Asynchronous Execution Example

{
  "Type": "ScriptCallActivity",
  "Name": "Trigger Background Task",
  "Alias": "BackgroundTask",
  "ScriptId": "BackgroundJob",
  "Wait": false,
  "Action": "Exit"
}

Example with Authorization

{
  "Type": "ScriptCallActivity",
  "Name": "Execute Secure Script",
  "Alias": "SecureScript",
  "ScriptId": "SecureOperation",
  "Wait": true,
  "Authorization": "Bearer {AccessToken}"
}

Complete Process Example

{
  "Name": "Data Processing Flow",
  "Activities": [
    {
      "Type": "BusinessActivity",
      "Name": "Prepare Data",
      "Alias": "PrepareData"
    },
    {
      "Type": "ScriptCallActivity",
      "Name": "Execute Data Transformation",
      "Alias": "TransformData",
      "ScriptId": "DataTransform",
      "Wait": true
    },
    {
      "Type": "BusinessActivity",
      "Name": "Check Result",
      "Alias": "CheckResult"
    }
  ]
}

Handling Script Execution Result Example

[Serializable]
[Design("Check Script Result", "Check script execution result", Sort = 1)]
[Category("Custom")]
public class CheckScriptResultActivity : BusinessActivity
{
    public override async Task ProcessAsync(ProcessflowEventArgs args)
    {
        var statusCode = (int)Flow.DataItems["TransformData_StatusCode"];
        
        if (statusCode == 200)
        {
            Flow.Logger.LogMessage("Script executed successfully", Name);
            Flow.DataItems["ScriptResult_Value"] = "Success";
        }
        else
        {
            Flow.Logger.LogErrorMessage($"Script execution failed: StatusCode={statusCode}");
            Flow.DataItems["ScriptResult_Value"] = "Failed";
        }
        
        await base.ProcessAsync(args);
    }
}

Extension Development Guide

Inheritance Hierarchy

Activity (SYC.Flow.Kernel)
  └── BusinessActivity
        └── ActionActivity
              └── ScriptCallActivity

Overridable Methods

Method Name	Usage	When to Override
ExecuteActionAsync	Execute script call	Need custom script calling logic

Custom Script Call Node Example

[Serializable]
[Design("Enhanced Script Call", "Script call node with retry", Sort = 1)]
[Category("Custom")]
public class EnhancedScriptCallActivity : ScriptCallActivity
{
    [Design("Retry Count", "Number of retries when script execution fails", Sort = 10)]
    [Category("Script Configuration")]
    public int RetryCount { get; set; } = 3;
    
    protected override async Task ExecuteActionAsync(ProcessflowEventArgs args)
    {
        for (int i = 0; i < RetryCount; i++)
        {
            await base.ExecuteActionAsync(args);
            
            var statusCode = (int)Flow.DataItems[$"{Name}_StatusCode"];
            if (statusCode == 200)
            {
                return;
            }
            
            Flow.Logger.LogWarningMessage($"Script execution failed, retry {i + 1}/{RetryCount}", Name);
            await Task.Delay(1000 * (i + 1));
        }
    }
}

Notes

• ⚠️ Script Configuration: Scripts must be configured in the base script management module before they can be used in the process.
• ⚠️ Status Code Check: Check the status code after the call to ensure the script executed successfully.
• ⚠️ Asynchronous Execution: When Wait=false, it is impossible to confirm whether the script executed successfully.
• ⚠️ Authorization: If script execution requires authentication, correct Authorization must be provided.
• ⚠️ Script Not Found: If the script corresponding to ScriptId does not exist, the node will record a warning and skip execution.
• 💡 Best Practices:
  • Check status codes after script calls to handle failures.
  • Add logs for script calls to facilitate troubleshooting.
  • Complex logic is recommended to be implemented in scripts rather than process nodes.
  • Sensitive information should be dynamically obtained from configuration or process context.

Related Nodes

• ActionActivity: Base class for script call nodes.
• ApiCallActivity: API call node.
• PythonScriptActivity: Python script node (inline script).
• MethodCallActivity: C# method call node.

Update History

Date	Version	Description
2025-11-28	1.0	Initial version

---

Last updated: 2025-11-28