Calling a workflow with external parameters

Campaign Standard lets you call a workflow with parameters (an audience name to target, a file name to import, a part of message content, etc.). This way, you can easily integrate your Campaign automations with your external system.

Let's take the following example, where we want to send emails directly from a CMS. In that case, you can configure your system to select the audience and email content into the CMS. Clicking on Send will then call a Campaign workflow with these parameters, enabling you to use them into the workflow to define the audience and URL content to use in the delivery.

The process to call a workflow with parameters is the following:

  1. Declare the parameters in the External signal activity. See Declaring the parameters in the External signal activity.

  2. Configure the End activity or the API call to define the parameters and trigger the workflow External signal activity.

Once the workflow triggered, the parameters are ingested into the workflow's events variables and can be used within the workflow. See Customizing a workflow with external parameters.

extsignal_process

Declaring the parameters in the External signal activity

The first step to call a workflow with parameters is to declare them in an External signal activity.

  1. Open the External signal activity, then select the Parameters tab.

  2. Click the Create element button, then specify the name and type of each parameter.

    Uzmanību!

    Make sure that the name and number of parameters are identical to what is defined when calling the workflow (see Defining the parameters when calling the workflow). Moreover, the parameters' types must be consistent with the values that are expected.

    extsignal_declaringparameters_1
  3. Once the parameters declared, finish the workflow configuration, then run it.

Defining the parameters when calling the workflow

This section details how to define parameters when calling a workflow. For more on how to perform this operation from an API call, refer to the REST APIs documentation.

Before defining the parameters, make sure that:

To configure the End activity, follow the steps below:

  1. Open the End activity, then select the External signal tab.

  2. Select the workflow and the external signal activity that you want to call.

  3. Click the Create element button to add a parameter, then fill in its name and value.

    extsignal_definingparameters_2

    Uzmanību!

    Make sure that all the parameters have been declared in the External signal activity. Otherwise, an error will occur when running the activity.

  4. Once the parameters defined, confirm the activity, then save your workflow.

Monitoring the events variables

It is possible to monitor the events variables that are available in the workflow, including the declared external parameters. To do this, follow the steps below:

  1. Select the activity that follows the External signal activity, then click the Log and tasks button.

  2. In the Tasks tab, click button.

    extsignal_monitoring_2
  3. The execution context of the task displays (ID, status, duration, etc.), including all events variables that are now available for use in the workflow.

    extsignal_monitoring_3

Customizing a workflow with external parameters

Once the workflow triggered, the parameters are ingested into the events variables and can be used to customize the workflow's activities.

They can, for example, be used to define which audience to read in the Read audience activity, the name of the file to transfer in the Transfer file activity, etc.

Activities that can be customized with events variables are detailed in this section.

Using events variables

Events variables are used within an expression that must respect the Standard syntax.

The syntax to use events variables must follow the format below, and use the parameter's name that has been defined in the External signal activity (see Declaring the parameters in the External signal activity):

$(vars/@parameterName)

When using a variable in an activity, the interface provides help to call it.

extsignal_callparameter
  • : select the events variable among all variables that are available in the workflow (see ).

    wkf_test_activity_variables
  • : edit expressions combining variables and functions. For more on the Expression editor, refer to this section.

    wkf_test_activity_variables_expression

Related topics:

Customizing activities with events variables

Events variables can be used to customize several activities, listed in the section below. For more on how to call a variable from an activity, refer to this section.

Read audience activity: define the audience to target based on events variables.

For more on how to use the activity, refer to the dedicated section.

extsignal_activities_audience

Test activity: build conditions based on events variables.

For more on how to use the activity, refer to the dedicated section.

extsignal_activities_test

Transfer file activity: customize the file to transfer based on events variables.

For more on how to use the activity, refer to the dedicated section.

extsignal_activities_transfer

Query activity: parameters can be referenced in a query, by using expressions combining events variables and functions. To do this, add a rule then click the Advanced mode link to access the expression editing window (see Advanced expression editing).

For more on how to use the activity, refer to the dedicated section.

extsignal_activities_query

Channels activities: personalize deliveries based on events variables.

To do this, you must first declare into the delivery activity the variables that you want to use:

  1. Select the activity, then click the button to access the settings.

  2. Select the General tab, then add the events variables that will be available as personalization fields in the delivery.

    extsignal_activities_delivery
  3. Click the Confirm button.

Declared events variables are now available from the list of personalization fields. You can use them in the delivery to perform the actions below:

  • Define the name of the template to use for the delivery.

    Piezīme.

    This action is available for recurring deliveries only.

    extsignal_activities_template
  • Personalize the delivery: when selecting a personalization field to configure a delivery, events variables are available in the Workflow parameters element. You can use them as any personalization field, for example to define the delivery subject, the sender etc.

    Delivery personalization is detailed in this section.

    extsignal_activities_perso

Segment codes: define the segment code based on events variables.

Piezīme.

This action can be performed from any activity that lets you define a segment code like, for example, Query or Segmentation activities.

extsignal_activities_segment

Use case

The use case below shows how to call workflow with parameters within your workflows.

The objective is to trigger a workflow from an API call with external parameters. This workflow will load data into your database from a file and create an associated audience. Once the audience created, a second workflow will be triggered to send a message personnalized with the external parameters defined in the API call.

To perform this use case, you need to perform the actions below:

  1. Make an API call to trigger Workflow 1 with external parameters. See Step 1: Configuring the API call

  2. Build Workflow 1: the workflow will transfer a file and load it into the database. It will then test if the data is empty or not, and eventually save the profiles into an audience. Finally, it will trigger Workflow 2. See Step 2: Configuring Workflow 1

  3. Build Workflow 2: the workflow will read the audience that has been created in Workflow 1, then send a personalized message to the profiles, with a segment code customized with the parameters. See Step 3: Configuring Workflow 2

extsignal_uc_process

Prerequisites

Before configuring the workflows, you need to create Workflow 1 and 2 with an External signal activity in each of them. This way, you will be able to target these signal activities when calling the workflows.

Step 1: Configuring the API call

Make an API call to trigger Workflow 1 with parameters. For more on the API call syntax, refer to the Campaign Standard REST APIs documentation.

In our case, we want to call the workflow with the parameters below:

  • fileToTarget: the name of the file that we want to import into the database.

  • discountDesc: the description that we want to display into the delivery for the discount.

-X POST https://mc.adobe.io/<ORGANIZATION>/campaign/<TRIGGER_URL>
-H 'Authorization: Bearer <ACCESS_TOKEN>' 
-H 'Cache-Control: no-cache' 
-H 'X-Api-Key: <API_KEY>' 
-H 'Content-Type: application/json;charset=utf-8' 
-H 'Content-Length:79' 
-i
-d {
-d "source:":"API",
-d "parameters":{
-d "fileToTarget":"profile.txt",
-d "discountDesc":"Running shoes"
-d } 

Step 2: Configuring Workflow 1

Workflow 1 will be built as below:

  • External signal activity: where the external parameters must be declared in order to be used within the workflow.

  • Transfer file activity: imports the file with the name defined in the parameters.

  • Load file activity: loads data from the imported file into the database.

  • Update data activity: insert or update the database with data from the imported file.

  • Test activity: checks if there is data imported.

  • Save audience activity: if the file contains data, saves the profiles into an audience.

  • End activity activity: calls Workflow 2 with the parameters that you want to use within it.

extsignal_uc_wkf1

Follow the steps below to configure the workflow:

  1. Declare the parameters that have been defined in the API call. To do this, open the External signal activity, then add the parameters' names and types.

    extsignal_uc1
  2. Add a Transfer file activity to import data into the database.To do this, drag and drop the activity, open it, then select the Protocol tab.

  3. Select the Use a dynamic file path option, then use the fileToTarget parameter as the file to transfer:

    $(vars/@fileToTarget)
    extsignal_uc2
  4. Load the data from the file into the database.

    To do this, drag and drop a Load file activity into the workflow, then configure it according to your needs.

  5. Insert and update the database with data from the imported file.

    To do this, drag and drop an Update data activity, then select the Identification tab to add a reconciliation criteria (in our case the email field).

    extsignal_uc3
  6. Select the Fields to update tab, then specify the fields to update in the database (in our case the firstname and email fields).

    extsignal_uc4
  7. Check if data is retrieved from the file. To do this, drag and drop a Test activity into the workflow, then click the Add an element button to add a condition.

  8. Name and define the condition. In our case, we want to test if the outbound transition contains data with the syntax below:

    $(vars/@recCount)>0
    extsignal_uc5
  9. If data is retrieved save it into an audience. To do this, add a Save audience activity to the Target not empty transition, then open it.

  10. Select the Use a dynamic label option, then use the fileToTarget parameter as the label of the audience:

    $(vars/@fileToTarget)
    extsignal_uc6
  11. Drag and drop an End activity that will call Workflow 2 with parameters, then open it.

  12. Select the External signal tab, then specify the workflow to trigger and its associated signal activity.

  13. Define the parameters that you want use within Workflow 2 and their associated values.

    In our case, we want to pass the parameters originally defined in the API call (fileToTarget and discountDesc), and an additional segmentCode parameter with a constant value ("20% discount").

    extsignal_uc7

Workflow 1 is configured, you can now build Workflow 2. For more on this, refer to this section.

Step 3: Configuring Workflow 2

Workflow 2 will be built as below:

  • External signal activity: where the parameters must be declared in order to be used within the workflow.

  • Read audience activity: reads the audience saved in Workflow 1.

  • Email delivery activity: sends a recurring message to the targeted audience, personalized with parameters.

extsignal_uc_wkf2

Follow the steps below to configure the workflow:

  1. Declare the parameters that have been defined in Workflow 1.

    To do this, open the External signal activity, then add the name and type of each parameter defined in the End activity of Workflow 1.

    extsignal_uc8
  2. Use the audience that has been saved in Workflow 1. To do this, drag and drop a Read audience activity into the workflow, then open it.

  3. Select the Use a dynamic audience option, then use the fileToTarget parameter as the name of the audience to read:

    $(vars/@fileToTarget)
    extsignal_uc9
  4. Name the outbound transition according to the segmentCode parameter.

    To do this, select the Transition tab, then the Use a dynamic segment code option.

  5. Use the segmentCode parameter as the name of the outbound transition:

    $(vars/@segmentCode)
    extsignal_uc10
  6. Drag and drop an Email delivery activity to send a message to the audience.

  7. Identify the parameters to use in the message to personalize it with the discountDesc parameter. To do this, open the activity's advanced options, then add the parameter name and value.

    extsignal_uc10b
  8. You can now configure the message. Open the activity, then select Recurring email .

    extsignal_uc11
  9. Select the template to use, then define the email properties according to your needs.

  10. Use the discountDesc parameter as a personalization field. To do this, select it from the personalization fields list.

    extsignal_uc13
  11. You can now finish configuring the message, then send it as usual.

    extsignal_uc14

Executing the workflows

Once the workflows built, you can execute them. Make sure the two workflows are started before performing the API call.

Šis darbs ir licencēts saskaņā ar Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported licenci  Uz portālā Twitter™ un Facebook izvietotajiem ziņojumiem neattiecas Creative Commons sistēmas noteikumi.

Juridisks paziņojums   |   Tiešsaistes konfidencialitātes politika