Skip to main content

Logic: Lambda

Zuora

Logic: Lambda

  1. Last updated
  2. Save as PDF

The Lambda task feeds data in the workflow payload into a predefined AWS Lambda function, triggers the function, and fetches the data in the result when the function completes. A Lambda function is a piece of AWS Lambda code that processes the data in the payload and returns the results to the workflow.

The Lambda task is in Limited Availability. If you wish to enable this task, submit a request at Zuora Global Support.

The Lambda task provides endless possibilities of what you can achieve and greatly extends the use scenarios of Workflow. For example, you can automate product price adjustments based on regional labor cost inflation by parsing data from source websites with the Beautiful Soup library in Python.

Zuora does not support debugging the Lambda codes developed by Zuora customers. All Lambda functions should include complete error handling logic so that errors can be captured in Workflow API calls. This is important for troubleshooting. For more information about how to debug your codes with the logs, see Monitor and troubleshoot a workflow.

Before you add a Lambda task, ensure that:

  1. You have access to the Lambda task in Workflow. 
  2. You have built a Lambda function. You can start with the Lambda starter package that is provided in the custom code upload window. 
    To learn about where to download the starter package, see step 4 in Upload a Lambda function in a workflow.
    To learn about implementation details and use cases of AWS Lambda, see the AWS Lambda introduction.
  3. You have uploaded your Lambda function to Workflow.
    To learn about how to upload your Lambda function, see Upload a Lambda function to a workflow.

Task settings

You need to select a function to run from the list of uploaded Lambda functions for your organization. 

workflow_task_lambda_functions.png

You can test your Lambda code by performing a test run with the data in the payload. To test your code, select the Testing tab and click Test Run. The data in the response will be shown in the right section.

workflow_task_lambda_testing.png

AWS Lambda function only returns the last 4 KB of the execution log in the response, which means the Log Result response section will be truncated if it is larger than 4 KB.

Upload a Lambda function to Workflow

  1. Ensure you have access to the Lambda task. Otherwise, you cannot upload a Lambda task.
  2. On the home page of Workflow, click the Settings tab. 
  3. In the Custom Code Executable section, click New.
  4. Configure the basic settings for your code and upload the code.
    • Function Name - A name to identify the function. Letters and underscore are accepted. Space is not accepted.
    • Handler - The handler is a function in your code that AWS Lambda can invoke when the service executes your code. Refer to AWS Lambda Documentation to learn more about handler syntax structures for different languages.
    • Runtime - The runtime for the programming language that you use. 
    • Code Upload - A Lambda starter package is provided in the window to help you get started. You need to implement at least one function that comes with the starter package and can import as many functions as you want.
  5. Optionally configure the environmental settings. 
  6. Click Create to upload your function. Uploaded Lambda functions can be used by all users in the same organization.

Guidelines about using Lambda tasks in Workflow

  • Do not include a Zuora API call in a Lambda task in Workflow. Instead, use existing Workflow tasks to fetch the Zuora data you need prior to the Lambda task.
    When using Workflow APIs in Lambda, you need to implement the logic to handle special scenarios like API rate limiting, temporary outages, and concurrent locking. Workflow has safeguards built-in to handle these scenarios, but Lambda does not. A Lambda developer would need to implement a series of safeguards on their own, like automatic scale backs, retries, and temporary processing pauses. It’s much easier to use existing Workflow tasks for fetching data from Zuora.

  • Do not implement a Workflow Lambda task that requires pooling from Zuora or an external system. Lambda has a 3-5 minute timeout. A slight delay in the external system can cause problems. These types of operations are best implemented in other ways. This is why the Export, Data Query, Bill Run, Payment Run, and Report Run are all implemented as dedicated Workflow tasks. They have sophisticated polling features built-in.

  • Do not implement a Workflow Lambda function if it is dependent on a stateful API that is not idempotent. If the API operation fails, the state might be lost inside the Workflow Lambda task. When possible, consider using the AQuA Query task instead. If the AQuA Query task is used, stateful operations are less likely to be lost. This is because Zuora's AQuA supports retrieving raw data change between the last API call and each subsequent API call.

A good example of using Lambda in Workflow

Upon the completion of payment runs, a user needs to send the ACH account numbers and routing numbers of their customers to payment gateways for payment processing. By default, the data payload in Workflow is not encrypted. To prevent sensitive data from being exposed, the user leverages the encryption option in the Export task. After the Export task, the user adds a Lambda task to decrypt the data and send the data to a specific SFTP destination. 

The encrypted export is an asynchronous process that normally takes a relatively long time to complete. If it is implemented in a Lambda task, the Lambda may time out before the complete set of data is retrieved. 

When you upload/delete a custom code executable function in a lower environment like the Sandbox, the same change is reflected in the Production environment also since a function uploaded will be shared across all environments and tenants within that organization.

Examples that Lambda is not a good fit

  • Lambda is used for advanced math calculations - not recommended

    A customer needs to use power functions to calculate the present value (PV) and the future market value (FMV) of a charge. The liquid template language does not help much in this regard. The user considers using Lambda to perform the calculations.

    Although this is achievable using Lambda, it would involve a lot of extra calculations and configurations. A more efficient approach is to use the Data Query task.

    With Data Query, the math operations could be used with the original charge amount and quantity to produce a CSV with the calculations already done. See below for the query being used in the Data Query task (with expressions calculating PV and FMV highlighted in blue).
    example_power_functions.jpg

  • Lambda is used for advanced lookup relations - not recommended

    A customer uses Lambda after an Export task to compare the data with an external lookup table to derive a value. This is not an efficient use of the Lambda task. Instead of using the Lambda task, the customer can add the lookup table as a global constant and insert it into a Data Query task via SQL. To learn about how to insert a global constant in a query, see the code section in the upper red rectangle. To learn about how data is fetched and joined with Zuora data, see the code lines in the lower red rectangle. 
    workflow_example_insert_lookup.jpg

  • Lambda is used for creating a custom file - not recommended

    A customer needs to create a fixed-width file that contains payment data. They consider using the Lambda task to create such a file and plan to use the first row of data in the file as the character string identifier. The character string identifier will be used for the destination system to identify the contents in the file. This is not an efficient use of Lambda.

    Alternatively, the customer can use the Data Query task, where the different rows could be concatenated and the overall row name could be expressed as the character string identifier. See below for an example query used in the task and the resulted CSV file.
    workflow_example_custom_file.jpg

    The CSV file can then be uploaded with the SFTP Upload task. Because the CSV contains only 1 column of data, when the CSV was uploaded, the filename will be changed to XYZ.txt.

  • Lambda is used for creating a custom file - not recommended

    A customer needs to create a custom CSV file with a specific column delimiter. They consider using the Lambda task so they could manipulate the exported data before sending it to the integrating system. This is not an efficient use of Lambda.

    Alternatively, the customer can consider using the new DSV option for File Delimiter in the Data Query task. After DSV is selected, the customer can specify the delimiter they want to separate the columns of the CSV.
    workflow_task_dq_dsv.png

  • Lambda is used for performing AQuA calls  - not recommended

    A customer tries to use Lambda to perform AQuA API calls. An AQuA call is an asynchronous process that could take longer than 3 minutes and is stateful. The state can be lost during the execution of the Lambda task, or the task may timeout during the polling operation for the file. 
    Alternatively, the customer can use the native AQuA Query task.