Navigation

Named Pipelines

Overview

Named pipelines are pipelines with names that can be referenced elsewhere within a MongoDB Stitch app and by clients of the app. Named pipelines have several capablities.

Procedure

Use the following procedure to define a named pipeline:

  1. Select your MongoDB Stitch app in the console. If you haven’t yet created a MongoDB Stitch app, see Getting Started.

  2. Click Pipelines in the left navigation pane.

  3. Click New Named Pipeline in the Named Pipelines view.

  4. Enter a name for the named pipeline in the Name field. The name must be unique within the MongoDB Stitch app where it is defined.

  5. You can specify any of the following pipeline properties:

    Property Description
    Private If selected, the pipeline may be called only from incoming webhooks, rules, and other pipelines defined in the MongoDB Stitch Admin console. Private pipelines may not be called from MongoDB Stitch client applications.
    Skip Rules If selected, the pipeline’s service actions bypass any rules and filters defined for those services. However, you must provide an expression in the Can Evaluate box when this capability is enabled.
    Can Evaluate An expression in the format of a JSON document that must evaluate to true before the pipeline may run. The expression can include expansions. An empty JSON document always evaluates to true, indicating that the pipeline can always be run. This pipeline-specific expression is evaluated before other service-specific rules. An expression is required when Skip Rules is enabled for the named pipeline.
    Add Parameter Specify parameters that can be accessed by any stage in the named pipeline with the %%args expansion. Select the REQUIRED checkbox to specify that a parameter is required to execute the pipeline.
  6. Build a pipeline stage. Each stage of a pipeline consists of the following:

    Service Any MongoDB Stitch service defined for the app, as well as the built-in service.
    Action An action associated with the selected MongoDB Stitch service.
    Arguments Arguments to pass to the selected service action. Access any variables defined for the stage using the %%vars expansion.
    Bind data to %%vars (Optional) Defines a variable for each key in the let component. The component is evaluated for each input document. To access parameters passed to the pipeline, you must bind parameters to variables to access them with a %%vars expansion.
  7. Click Done to save the pipeline stage.

  8. (Optional) To add additional stages to the pipeline, click Add Stage and repeat the steps to create a stage.

  9. Select an output type from the list next to the Save button.

    • To return a single document processed by the pipeline, choose Single Document.
    • To return a boolean value indicating whether the pipeline returned any output, choose Boolean.
    • To return all documents processed by the pipeline, choose Array.
  10. Click Save.

Example

The sendSMS named pipeline consists of two stages. The first stage retrieves the phone_number field from every document in the todo.users collection in a MongoDB database. The second stage sends a Twilio SMS to each number with the same body text and from the same number.

Prerequisites

The sendSMS named pipeline assumes you have configured the following services for your MongoDB Stitch app:

You must create a namespace for the todo.items collection in your MongoDB service. At least one of the documents in this collection must contain the following:

  • a phone_number field containing a valid Twilio number
  • an owner_id field containing the the user id of the user who inserted the document into the collection
{"owner_id":"593ac52657e0fa71da4d666d","name":"Anita Jones","phone_number":"+14159509312"}

Define First Stage

The first stage in the named pipeline performs a find action on the mongodb-atlas service. The arguments for the service use the $exists operator to verify that only documents with a phone_number field are retrieved and passed to the next stage.

../../_images/named-pipeline-stage1.png

Define Second Stage

The second stage of the pipeline performs a send action on the tw1 Twilio service. The stage includes a let component that creates the following variables:

  • to: Assigns the value of the phone_number document field of each output document from the previous stage to the to argument of the current stage. Argments to the current stage access this variable with the %%vars.to expansion.
  • from: Assigns +14159509312 to the from argument of the current stage. Arguments to the current stage access this variable with the %%vars.from expansion.
  • body: Assigns a concatentation of the name field from each output document from the prior stage and ", please confirm your attendance." to the body argument of the current stage. The arguments to the current stage access this variable with the %%vars.body expansion.
../../_images/named-pipeline-stage2.png

Test a Named Pipeline

Use the following procedure to test a named pipeline:

  1. Click Debug Console in the left navigation pane.

  2. Click choose user to choose a user to execute the pipeline.

  3. Click +Add Stage.

  4. Verify that built-in is selected from the SERVICE list and literal is selected from the ACTION list.

  5. Enable Bind data to %%vars.

  6. Enter the following let component in the box below Bind data to %%vars to create a variable named output:

    {
      "output": {
        "%pipeline": {
          "name": "sendSMS"
        }
      }
    }
    

    Note

    You can choose any key, or name, for your %pipeline block. This example uses output.

  7. Enter the following JSON document in the box above Bind data to %%vars to create a variable named output and associate it with the vars expansion:

    {
      "items": [
        "%%vars.output"
      ]
    }
    
  8. Click Done.

  9. Click Execute.

An SMS message is sent to each document displayed in the Result box.

Executing Named Pipelines in Client Code

The StitchClient provides a executeNamedPipeline() function to execute named pipeline from your application code. For example:

copyable-code
import { StitchClient } from 'stitch';

const stitchClient = new StitchClient('<your-app-id>');

stitchClient.executeNamedPipeline('<name>', <args document>);
  • Replace <your-app-id> with your MongoDB Stitch app ID. In the MongoDB Stitch console, you can find your App ID in the Clients view.
  • Replace <name> with the name of your pipeline.
  • If specifying arguments, replace <args document> with the parameters for your named pipeline. Omit <args document> if you are not specifying arguments.
←   send Expansions  →