Return

In order to finalize a process execution in Frends, Return shape is used. It is the end element that, optionally, returns a value to the caller, if the Process had any. In general, if the Process was executed successfully, this shape is used to log a successful Process Instance, and any resulting value needed for logging purposes.

What is Return?

When a Process is complete, Return shape is used to end the Process. It can be configured to send a response to HTTP or API caller as HTTP response, or save a result value from the Process to instance logs. It also implicitly means that the Process execution was successful, logging a successful execution of the Process.

Return shape is also used to complete a Scope shape, marking the end point of a scoped execution or iteration. In this use case Return specifies the result value for that Scope or single iteration. In the case of loops, the results from each iteration is built into an array of values from the Return shape to be the complete result value for that shape.

While it identifies a successful execution of the Process, it can be used to return an error state to the caller through return values, as Process execution can be technically successful, but the result is an error for the caller. Success in this scenario is viewed from the integration developer perspective.

Types of Returns

There are three different types of configurations for Return shape. All of them provide a return value, accessible through #result reference value if used within a Scope, that will also be returned to caller and to logging when used at the end of a Process. The type of Return shape used determines the data format and fields of the result value.

Expression

This is the standard Return shape, able to return any and all formats of data when specified using a C# expression, or basic text content that can be enhanced using Handlebars syntax. It only has an expression field to which the result value can be specified to.

This type of Return shape can replace the other two Return shape types, if the result value is defined as HttpResponse or HttpBinaryResponse object.

HTTP Response

This Return shape type is specifically tailored to provide a response to an HTTP or API call. Instead of single, free-to-use in anyway you like field, the configuration parameters include fields for HTTP status code, body content for the HTTP response, content type and encoding, as well as possible header values to include in the response.

HTTP Binary Response

Like HTTP response, but this type is specifically returing binary data as content in the response, such as a file. The binary data is given as bytes in Base64 encoded string, which is then converted to binary data for the receiver. The return type includes HTTP status code, content type specification as well as possible HTTP headers.

Usage

Return shape is usually the last element in a Process, specifying successful end for the Process and optionally a return value. Instead of ending a Process successfully, a Throw shape can be used to raise an error at the end of a Process. After adding a Return shape to the Process canvas and connecting it to the rest of the Process, you can set a type for the shape and configure its parameters.

A Process can have as many return values as you want, but the Process logic must work so that only one Return shape is executed. Two simultaneously executed branches of a Process cannot end in different Return shapes, but must instead converge back into a single shape before ending the Process. Decision shapes can be used to select alternative Return shapes, or Throw shapes, to fulfill the integration logic requirements.

Any and all container shapes must also end their internal Process flow into a Return shape. They can also contain multiple Return shapes with same caveats as in the Process in general. For the iterative containers, Return shape does not interrupt the iteration, but instead signifies the end of each iteration's logic flow.

The result value specified in Return shape at the end of a Process will be returned to the caller, if the Process was triggered with HTTP or API call. Same value will also be logged in Process Instances as the result of that Process. Values specified at the end of a container shape will available through #result reference value for that container, as a single value or object for a Scope, and as an array of values for an iterative shape.

Architecture

When used to provide a response to HTTP or API caller, if the connection between Frends and the caller is still open, the connection will be closed as complete once the response is sent back. In case the connection has closed before the response could be sent, because of connection error, timeout or through the usage of Intermediate Return shape, the HTTP response cannot be sent back to the caller.

Execution of a Return shape at the end of a Process will signal the Frends platform that the Process execution has ended, and it was successful. If the log settings and shape configuration allows it, the result is saved as the Process execution's result into the logs.

Configuration

To set up a Return shape, add it to your Process canvas and connect it to your Process flow using a Sequence flow. After this, you can configure the shape to required type and values.

The following configuration parameters exist for Return shape and its alternative shapes.

Display name

Shapes can be given a display name in Frends Processes to distinquish them from each other. Shape's display name has no technical purpose and is only for documentational and visual purposes only. For shapes returning a #result reference value, the display name can be used to specify which result is meant.

Display name is given to the shape by double-clicking it on the canvas or through its configuration parameters.

Type

Return shape's type specifies what kind of object it will return and thus what configuration parameters it has available. Defaults to Expression. You can view the possible values and their meaning above, at Types of Returns.

Skip logging result and parameters

Toggle option to select if the values of this shape should be included in logging or not. Default is false. If set to true, Process Instance logs will show the result and parameter values of this shape as << Omitted >>.

Promote result as

Toggle option to select if the result value of this shape should be promoted in the Process Instance list, and an text input field if set to true. Default is false. Promoted values appear in the Process Instance list in their own column along with error and result values. Promoted value column is named with the text input field appearing when this is set to true.

Promoted values are always logged fully in the Process Instance view, regardless of the log level settings.

Expression

Dynamic text input field which is available, if Return shape's type is set as Expression. Defaults to #result expression. This field is used to specify the result value of a Process or Scope either as C# expression or basic text input with Handlebars syntax enabled.

HTTP Status Code

Dynamic numeric input field which is available, if Return shape's type is set as HTTP Response or HTTP Binary Response. Defaults to 200. Field is used to specify HTTP response's status code, either as numerical value or C# expression.

HTTP Content

Dynamic text input field which is available, if Return shape's type is set as HTTP Response. Defaults to empty. Field is used to specify HTTP response's body, either as basic text input with Handlebars syntax enabled, or as C# expression.

HTTP Content Bytes

Dynamic text input field which is available, if Return shape's type is set as HTTP Binary Response. Defaults to empty. Field is used to specify HTTP response's body as base64 encoded byte array, either as basic text input with Handlebars syntax enabled, or as C# expression.

HTTP Content Type

Dynamic text input field which is available, if Return shape's type is set as HTTP Response or HTTP Binary Response. Defaults to application/json. Field is used to specify HTTP response's content type, either as basic text input with Handlebars syntax enabled, or as C# expression.

HTTP Content Encoding

Dynamic text input field which is available, if Return shape's type is set as HTTP Response. Defaults to utf-8. Field is used to specify HTTP response's content encoding, either as basic text input with Handlebars syntax enabled, or as C# expression.

HTTP Headers

Array of key-value pairs which is available, if Return shape's type is set as HTTP Response. Defaults to empty array. Field is used to specify HTTP response's additional header values, either as manually entered set of elements including key-value pairs, that are input by using basic text values with Handlebars syntax enabled, or as C# expressions, or by providing the whole list of key-value pairs as C# expression.

Reference values

Return shape is used to specify Scope shape's #result reference value.

#result

#result reference value can be used to access earlier shape's return value. For Scope shapes, the value is specified using Return shape, while for Task's the #result is populated directly by the Task.

When Return shape is used to end Foreach or While shapes, the expression or HTTP content values in Return shape are available through #result reference value as an array of values for each iteration.

#result reference value by default references the last Task's or Scope shape's return value. Instead of unnamed #result reference, you can also use named #result reference value.

Named #result

Named #result reference value is used with square brackets, much like dictionary's or object's fields would be used, such as #result[Handle elements] or #result[HTTP Request]. This way it can be specified which shape's result you are using.

When using named #result reference value with Scope shapes and Return shapes, it should be noted that the #result reference value is named by the Scope shape and not by the Return shape, although the value is specified in the Return shape. Thus, when using the named #result value, such as #result[Handle elements], the Scope shape's name should be used.

Examples

You can learn more about using Return shape from the following examples.

How to create a Process

Integration flows in Frends are referred to as Processes. Processes consist of elements such as Triggers, Tasks, Subprocesses, decisions and loops. Processes are created by connecting elements together and configuring their parameters.

Step by Step Tutorial Available

If you prefer more visual or interactive guidance on how to create Processes with Frends, you can find a step-by-step walkthrough from your own environment's home page, under Onboarding by selecting "Tutorial 1, Step 3: Creating my first Process" tutorial.

Creating New Process

The Process list displays the already created Processes in the Environment.

In order to create a new Process, click on Create New button while in Process list view and having the Development Environment selected. All new Processes have to be created and edited in the Development Environment, from where they are then deployed to other Environments and Agent Groups for execution.

When creating a new Process, you can start by providing the Process a name and optionally a description. To use the latest versions in Frends, targeting .NET 8 is recommended, while .NET Framework 4.7.1 or .NET Standard 2.0 are only used to support legacy environments.

As an example, let's create a Process which is started manually without parameters, calls an API endpoint and then returns a result. Because the start element, called Trigger, is already provided, we can continue forward by adding a Task to the process.

You can drag or click and place the Task shape from the leftside toolbar to right of the Trigger shape.

To make the Task perform an API call, click on the Select a Task field and search and select HTTP Request Task. When the Task type is selected, the right sidebar contents change to show the Task parameters. In here, enter the url as https://examplecrm.frends.com/api/customers and make sure Method is GET. Rest of the options can be left as-is for this example.

Once the Task is configured for our use, we need to connect it to the earlier shape. To do this, click on the Connect tool from the left toolbar or from the quick toolbar next to the Trigger shape, and draw an arrow from the Trigger to the Task shape.

Finally, we need to end the Process and save it. All Processes start with a Trigger, and end to a Return shape, or optionally to a Throw shape. Let's drag a Return shape to the right side of the Task, and connect it to the Task shape to create a complete Process flow.

For the example, we want to return the API response's body. We can do this by selecting the Return shape, and writing #result[HTTP Request].Body to the Expression field. Make sure the field's type is set to Expression, and not Text, in order to Frends consider the content as C# code and not text.

Once ready, we can validate and save the process. You can optionally provide a Description or a comment to version history, what was changed in this version. It's recommended to always include a short comment on what was done.

Validation at this point means that the Process is taken through C# compiler and checked for errors, but it does not save the Process in any way. To save the Process for testing and deployment, select Create new Process. Saving the Process also validates it for errors, but save is not done if any errors persist.

When editing a Process, the save button changes to Save changes. If you want to save your Process but not create a new version for use yet, you can instead select Create new draft from the small arrow menu. This way you can save your work even if the Process is not yet valid.

Once the saving and validation succeeds, you are taken back to Process list view with your new Process highlighted at the top of the list. From there, you can run it, deploy it or continue editing, among other options.