In the task step of Serverless workflow, you can send messages to a specified Message Service (MNS) queue. This topic describes the scenarios, common parameters, integration modes, and permission configurations for integrating MNS queues.

Scenarios

You can integrate the MNS queues in the task step in the request/response and wait-for-callback modes. The following table lists the scenarios of these two modes.

Integration mode Parameter Scenario Description
Request/response mode requestResponse Event notification Services other than flow execution are persistently notified, and the flow execution is irrelevant to how the notified services process the message.
Wait-for-callback mode waitForCallback Orchestration of custom task types After a task executor in an environment, such as an Elastic Compute Service (ECS) virtual machine or a server in an on-premises data center, receives a message sent to a queue, the task executor calls back Serverless workflow after it executes the relevant task. For more information, see Best Practices.

Common parameters

In the following example, Serverless workflow sends a message to the queue specified in resourceArn. The specified queue name replaces {queue-name}. The body and parameters of the message are specified in serviceParams. The following content lists the supported parameters:

  • MessageBody: The body of the message, which is required. MessageBody: $: The message body is generated by inputMappings. The following content describes how the message body is generated when the step enters the StepEntered event:
    • The input object is {"key": "value_1"}.
    • The mapped input is {"key_1": "value_1", "key_2": "value"}.
    • The task step uses the {"key_1": "value_1", "key_2": "value"} string as the message body and sends it to the MNS queue.
  • Priority: The priority of the message, which is required.
  • DelaySeconds: The message latency, in seconds. The parameter is optional.

For more information about parameters, see SendMessage in MNS documentation.

version: v1
type: flow
steps:
 - type: task
   name: Task_1
   resourceArn: acs:mns:::/queues/{queue-name}/messages  # The task step sends messages to the MNS queue named {queue-name} under the same account in the same region.
   pattern: requestResponse                              # The task step ends after the message is sent to the MNS queue.
   inputMappings:
      - target: key_1
        source: $input.key
      - target: key_2
        source: value
   serviceParams:     # The service integration parameters.
      MessageBody: $  # The mapped input is used as the body of the message you want to send.
      DelaySeconds: 0 # The message latency, in seconds.
      Priority: 1     # The priority of the MNS queue.

Integration modes

  • Request/response mode

    The pattern: requestResponse parameter of the task step indicates the request/response mode. In this mode, Serverless workflow sends a message to the {queue-name} queue specified in resourceArn. After the message is sent, the step is completed. If the message fails to be sent, the step fails or is retried based on the retry configurations.

    version: v1
    type: flow
    steps:
     - type: task
       name: mytask
       resourceArn: acs:mns:::/queues/{queue-name}/messages  # The task step sends messages to an MNS queue under the same account in the same region.
       pattern: requestResponse                              # The task step ends after the message is sent to the MNS queue.
       inputMappings:
          - target: key_3
            source: value
       serviceParams:     # The service integration parameters.
          MessageBody: $  # {"key_3": "value"} is sent as the message body to the MNS queue.
          DelaySeconds: 0 # The message latency, in seconds.
          Priority: 1     # The priority of the MNS queue.
  • Wait-for-callback mode

    In the task step, pattern: waitForCallback indicates the wait-for-callback mode. In this mode, Serverless workflow sends a message to the {queue-name} queue specified in resourceArn. After the message is sent, the step suspends and waits for a callback. The task executor needs to use the corresponding task token to call back Serverless workflow. If the callback result indicates that the call to ReportTaskSuccceeded is successful, the task step is successful. If the callback result indicates that the ReportTaskFailed operation was called, the step fails or is retried based on the retry configuration.

    taskToken: The task token can be obtained from the context object of this step. inputMappings is used to assign taskToken to a field in the JSON object of the message body. In the following example, the context object in this step is {"task":{"token":"my-token-1"}}. The mapped task input is {"task_token": "my-token-1", "key": "value"}, which is also sent as the message body to the MNS queue.

    version: v1
    type: flow
    steps:
     - type: task
       name: mytask
       resourceArn: acs:mns:::/queues/{queue-name}/messages  # The task step sends messages to the MNS queue named {queue-name} under the same account in the same region.
       pattern: waitForCallback  # The task step suspends after the message is sent to the MNS queue and waits until it receives the callback.
       inputMappings:
          - target: task_token
            source: $context.task.token  # Serverless Workflow queries the task token from the context object.
          - target: key
            source: value
       serviceParams:     # The service integration parameters.
          MessageBody: $  # The mapped input is used as the body of the message you want to send.
          Priority: 1     # The priority of the MNS queue.

Flow role configuration

Serverless workflow assumes the RAM role specified by the flow to obtain your temporary AccessKey pair to access MNS on your behalf. Therefore, you must grant the flow role the SendMessage permission to send messages to MNS. You can select either a system policy or a custom policy to grant Serverless workflow the permission to send messages to your MNS queue.

  • System Policy: grants the AliyunMNSFullAccess system permission to the flow role.
  • Custom Policy: If you only allow the flow role to send messages to the {queue-name} queue, create the following policy and bind it to the flow role.
    {
      "Version": "1",
      "Statement": [
        {
          "Action": "mns:SendMessage", 
          "Resource": "acs:mns:*:*:/queues/{queue-name}/messages",
          "Effect": "Allow"
        }
      ]
    }