--- schema_version: "1" id: a5adebf24e00aa8a0dea3b855b8ba561b1db985150b1da4f1829c013917f4403 title: Operations collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/connector-builder/operations.md canonical_url: https://docs.mulesoft.com/connector-builder/operations source_site: docs.mulesoft.com content_type: documentation content_hash: a74294d551f18491e2320ec1a93d6860b3d96427cd20cc445d98989b66a5e7f1 description: MuleSoft Documentation Site latest: true --- --- product: Connector Builder version: master --- # Operations > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Learn how to define operations for your connector. Operations are the actions that your connector can perform, for example, CRUD (Create, Read, Update, Delete) operations. Platform-specific operations are defined as transformations of the canonical connectivity model (CCM) operations. You can define operations using either the UI or LinkWeave. Use the UI as your primary approach, as it significantly reduces manual development effort. Reserve LinkWeave for advanced scenarios that require custom logic. With Connector Builder, the goal is to focus on reviewing and validating the generated process, rather than writing custom code. ## Define Operations Using the UI When you [generate base connectivity](https://docs.mulesoft.com/connector-builder/base-connectivity), the operations defined in your API specification or AI assistance are automatically displayed as API endpoints. You can choose which operations to include in your connector by selecting or deselecting them. If you have already generated base connectivity and want to modify the set of operations included from your API specification or AI assistance, select **Generate** > **Regenerate Project** and choose which operations to add or remove. If you have already generated base connectivity and want to add operations that aren’t present in the API specification or AI assistance, update the API specification or AI input with the new operations, and then regenerate base connectivity. ### Execute Operations Using the Try It Panel The Try It panel lets you execute any operation directly from the editor at design time, without packaging or deploying the connector. The Try It panel is available for all operations, regardless of platform and regardless of whether they’re associated with a generated connector. 1. In the **Operations Explorer**, select an operation. The **Try It** panel appears on the right. 2. Select the authentication to use. You can either: - Use a **connection profile** (reusable credentials). Select an existing profile, or create a new one. See [Use Connection Profiles](https://docs.mulesoft.com/connector-builder/connections#use-connection-profiles). - Use **inline credentials** (fire-and-forget). The Credentials Editor appears, pre-populated with the expected JSON schema for the selected authentication scheme. Fill in the values. Inline credentials are discarded when you select a different operation. 3. In the **Input** editor, provide input for the operation. The Input editor is pre-populated with the expected JSON schema, including all fields. Required and optional fields are both shown. Modify the values you need and remove any optional fields you don’t want to send. 4. Click **Run**. 5. After the operation completes, the panel displays the result status and the response body. 6. If the operation supports pagination and additional pages are available, **Previous** and **Next** buttons appear. Click them to re-execute the operation against the corresponding page. ### Manage Operations with MCP Tools (Cursor) 1. Open the Connector Builder extension in Cursor. 2. Select **Settings** and ensure **Enable Mcp Tools** is enabled. 3. Open the Cursor chat window (if not already open). 4. Ask the agent to manage operations. For example, enter `List operations`, `Get operation details`, or `Execute an operation`. If you want to execute an operation, you need the connection profile ID. Use the `uc_list_connection_profiles` MCP tool first to [list connection profiles](https://docs.mulesoft.com/connector-builder/connections#list-connection-profiles-with-mcp-tools) to retrieve the ID. 5. Enter the required inputs when prompted. 6. Confirm your inputs. Connector Builder performs the requested action. For more information, see [MuleSoft DX MCP Server Tool Reference](https://docs.mulesoft.com/mulesoft-mcp-server/reference-mcp-tools). ## Define Operations Using LinkWeave You can define operations using LinkWeave. - [Operation Structure](#operation-structure) - [Operation Decorators](#operation-decorators) - [HTTP Operations](#http-operations) - [Operation Errors](#operation-errors) ### Operation Structure Each operation consists of: - `name`: An internal identifier for the operation. - `displayName`: The user-facing name shown in the UI. - `executor`: The function that implements the operation logic. Operation invocations can either succeed or fail. A successful invocation returns `ResultSuccess`, while a failure returns `ResultFailure`. The meaning of "failure" depends on the external service you’re integrating with. > [!NOTE] Most HTTP services indicate errors using `4XX` or `5XX` status codes, which the HTTP > library interprets as failures. However, some APIs always return `2XX` status codes and instead > signal errors within the response body. For these APIs, you must inspect the response and > explicitly signal failure in your executor. Operations have the `Operation` type. - `ArgsT`: The type of arguments required for invocation. It must be an `Object` type. - `OkT`: The type of the successful result (`ResultSuccess`). - `ErrorT`: The type of the failure result (`ResultFailure`), in which `ErrorValueType` is the error payload and `ErrorType` describes the error kind and categories. - `ConnT`: The connection type, which is an `Object` type that describes the context required to invoke the operation. Here’s an example of an operation: ```none type DuplicateParams = { x: Number } var myOperation: Operation, {}> = { name: "duplicate", displayName: "2 times X", executor: (args: DuplicateParams, connectionInstance) -> success(args.x * 2) } ``` ### Operation Decorators The `com::mulesoft::connectivity::decorator::Operation` module provides decorators to append additional code before or after an operation invocation. These decorators include: - `mapInputOperation(operation, mapper)`: Transforms the input before invoking the operation, adapting it to the type expected by the operation. - `mapInputPaginatedOperation(operation, mapper)`: Transforms the input before invoking a paginated operation, adapting it to the type expected by the operation. - `mapOutputSuccessOperation(operation, mapper)`: Transforms the output of successful invocations into a more suitable shape. - `mapOutputFailureOperation(operation, mapper)`: Transforms the output of failed invocations into a more suitable shape. - `mapOutputFailurePaginatedOperation(operation, mapper)`: Transforms the output of failed invocations of paginated operations into a more suitable shape. - `paginate(operation, strategy)`: Applies a pagination strategy to the output of successful invocations, using a function that receives both the original parameters and the successful result to create a `Page`. ### HTTP Operations HTTP operations are the most common type of operation, so they have the `com::mulesoft::connectivity::transport::Http` dedicated module. This module standardizes HTTP operation shapes and provides utilities for parameter encoding and request execution. Here’s a summary of the module. - `HttpRequestBuilder`: The base type for HTTP connection instances. - `HttpResponse`: The type representing an HTTP response with a body of type `T`. - `HttpAuthenticationType`: The type representing authentication for HTTP connections. - `HttpConnection`: The type describing an HTTP connection that requires parameters of type `ArgsT` and uses the specified `AuthenticationType`. - `BasicHttpConnection`: The type describing an HTTP connection using the Basic authentication scheme, requiring parameters of type `ArgsT`. - `defineBasicHttpConnection(validate, mapper)`: Defines `BasicHttpConnection` by providing a `validate` function to check credential validity and a `mapper` function to extract the authentication schema from the connection parameters. - `defineBearerHttpConnection(validate, mapper)`: Defines `BearerHttpConnection` by providing a `validate` function to check credential validity and a `mapper` function to extract the authentication schema from the connection parameters. - `BaseAuthSchema`: The base type for all authentication schemas. - `BasicAuthSchema`: The type describing the information required for the Basic authentication scheme. - `basicAuth(schema)`: Creates an HTTP connection instance (`HttpRequestBuilder`) from `BasicAuthSchema`. - `BearerAuthSchema`: The type describing the information required for the Bearer authentication scheme. - `bearerAuth(schema)`: Creates an HTTP connection instance (`HttpRequestBuilder`) from `BearerAuthSchema`. - `HttpOperation`: The type representing an HTTP operation. - `parseQueryParameters(uri)`: Parses query parameters from the given URI. - `addQueryParameters(resource, queryParams, config?)`: Serializes `queryParams` (using the optional `config`) and adds them to the specified resource. HTTP operations have the `HttpOperation` type, in which: - `ArgsT` must extend `HttpRequestType`. - `OkT` and `ErrorT` must extend `HttpResponse`. - `ConnT` must extend `HttpConnection`. The `HttpRequestType` object defines these parameters for all HTTP operations. - Query parameters (required, can be empty) - URI/path parameters (optional) - Header parameters (required, can be empty) - Cookie parameters (required, can be empty) - Body (optional) Here’s an example of an HTTP operation with the `http://www.mulesoft.com/user/{userId}` endpoint: ```none type GetUserByIdRequest = HttpRequestType<{| uri: { userId: Number }, query: {}, headers: {}, cookie: {} |}> @OperationElement() var GetUserByIdEndpoint: HttpOperation = { name: "getUserByIdEndpoint", displayName: "Get user by id", executor: (parameter, connection) -> success(connection({method: "GET", path: "/user/" ++ parameter.uri.userId}) as HttpResponse) } ``` The `parameter` variable is of type `GetUserByIdRequest`. To access individual parameter values, reference their corresponding attributes, as shown with `parameter.uri.userId` in the example. To perform HTTP requests, use the `request` function from `dw::io::http::Client`. To serialize complex values for query parameters, use the `addQueryParameters` function. #### Encoding Parameters in HTTP Operations Before sending parameters in an HTTP request, they often need to be converted into an appropriate string format. Specify the encoding configuration for each parameter that requires it. For example, array query parameters must be encoded into a string when constructing the final URI, as arrays can’t be transmitted directly. The same principle applies to URI, header, and cookie parameters, though each type might have different encoding options. For more information about the available encoding configurations for each parameter type, refer to [Style Values](https://spec.openapis.org/oas/latest.html#style-values). Here’s an example of encoding parameters in an HTTP operation: ```none type GetUsersByCompaniesIdEndpointRequest = HttpRequestType<{| uri: { companiesId: Array }, query: { users: Array }, headers: { customHeader: CustomAuth }, cookie: { customCookie: CustomAuth } |}> type CustomAuth = { username: String, pass: String } @OperationElement() var getUsersByCompaniesIdEndpoint: HttpOperation = { name: "getUserByIdEndpoint", displayName: "Get user by id", executor: (parameter, connection) -> success(connection({ method: "GET", path: "/usersByCompaniesId/" ++ serializeUriParam(parameter.uri.companiesId, config: { style: "simple", explode: false }), queryParams: parameter.query update { case users at .users -> users <~ { style: "form", explode: true } }, headers: parameter.headers update { case customHeader at .customHeader -> serializeHeaders(customHeader, config: { style: "simple", explode: false }) case Cookie at .Cookie! -> serializeCookies(parameter.cookie update { case customCookie at .customCookie -> customCookie <~ { style: "form", explode: false } }) } }) as HttpResponse) } ``` - **Query parameter encoding** To encode query parameters, add metadata to each parameter within the `queryParams` object of the HTTP request. The encoding is performed automatically before the request is sent. ```none queryParams: parameter.query update { case users at .users -> users <~ { style: "form", explode: true } } ``` - **URI/path parameter encoding** To encode URI parameters, call the `serializeUriParam` function for each parameter, passing the parameter and its encoding configuration. ```none path: "/usersByCompaniesId/" ++ serializeUriParam(parameter.uri.companiesId, config: { style: "simple", explode: false }), ``` - **Header and cookie encoding** To encode headers, call the `serializeHeaders` function for each header (except for the `Cookie` header), providing the parameter and encoding configuration. To encode cookies, call the `serializeCookies` function with the cookie object and encoding information for each parameter. ```none headers: parameter.headers update { case customHeader at .customHeader -> serializeHeaders(customHeader, config: {style: "simple", explode: false}) case Cookie at .Cookie! -> serializeCookies(parameter.cookie update { case customCookie at .customCookie -> customCookie <~ { style: "form", explode: false } }) } ``` ### Operation Errors Operations can fail in different ways, especially when interacting with HTTP endpoints that might return various status codes. This approach only signals that a failure occurred, without providing specific error kinds or categories: ```none var getUsers: Operation<{}, HttpResponse<{items: Array<{id: String, name: String, email: String}>, nextUrl?: String}>, ResultFailure, HttpConnection> = { name: "getUsers", displayName: "Get Users", executor: (parameter, connection) -> do { var response = connection({method: 'GET', path: "/users"}) --- if (response.status == 200) success(response as HttpResponse<{items: Array<{id: String, name: String, email: String}>, nextUrl?: String}>) else failure(response) } } ``` #### Example: Error Types To allow users to handle specific error types, such as `404 Not Found`, define error types and return them accordingly: ```none type Error404 = Error<"404", "CLIENT_ERROR"> var Error404Instance: Error404 = { kind: "404", categories: ["CLIENT_ERROR"] } var getUsers: Operation<{}, HttpResponse<{items: Array<{id: String, name: String, email: String}>, nextUrl?: String}>, ResultFailure, HttpConnection> = { name: "getUsers", displayName: "Get Users", executor: (parameter, connection) -> do { var response = connection({method: 'GET', path: "/users"}) --- if (response.status == 200) success(response) else if (response.status == 404) failure("404", Error404Instance) else failure("unknown error") } } ``` With this pattern, users can distinguish and handle specific error kinds at runtime. #### Example: Multiple Error Values Some external systems return different error payloads for different error types. For example, `4XX` and `5XX` return different messages: ```none type Error404 = Error<"404", "CLIENT_ERROR"> var Error404Instance: Error404 = { kind: "404", categories: ["CLIENT_ERROR"] } type Error500 = Error<"500", "SERVER_ERROR"> var Error500Instance: Error500 = { kind: "500", categories: ["SERVER_ERROR"] } type 404ErrorMessage = { message: String } type 500ErrorMessage = { errorCode: Number } var getUsers: Operation<{}, HttpResponse<{items: Array<{id: String, name: String, email: String}>, nextUrl?: String}>, ResultFailure<404ErrorMessage, Error404> | ResultFailure<500ErrorMessage, Error500>, HttpConnection> = { name: "getUsers", displayName: "Get Users", executor: (parameter, connection) -> do { var response = connection({method: 'GET', path: "/users"}) --- if (response.status == 200) success(response) else if (response.status == 404) failure({message: "404 Not Found"}, Error404Instance) else failure({errorCode: 500}, Error500Instance) } } ``` In this example, a `4XX` error returns a `{message: String}` payload, while a `5XX` error returns `{errorCode: Number}`. This allows users to handle and inspect error payloads based on the error kind.