Lambda

Note: Contact your skuid representative to access this feature.

AWS Lambda is a "serverless" compute service—meaning that it processes functions and returns their results without needing a full operating system running on a server. These functions can be written in a variety of programming languages and can receive inputs from external services. They can return either an error or success response based on the inputs provided. Because of this server-side processing, Lambda functions can be used to extend the capabilities of what Nintex Apps can accomplish in your frontend application experiences.

There are many types of server-side processes which should run on a server—not in the browser—such as complex data transformation, image or video manipulation, document generation, etc. By defining these processes as Lambda functions, you can invoke them from a variety of services, including Nintex Apps. of delving into specific Lambda uses, this doc covers the basics of configuration and use in Nintex Apps.

For more information about how to create your functions, refer to AWS resources:

Configuration

AWS access permissions

When using AWS APIs, it is best practice to utilize strict and well-defined IAM policies so end users can only perform actions they have explicit access to.

Listed below are the permissions this connector requires to properly function. Use this list to better define your IAM roles.

  • lambda:InvokeFunction
  • lambda:ListFunctions

Creating an AWS authentication provider

Before configuring connections within Nintex Apps, you need to decide how you'll authenticate to your AWS services using an IAM role. We recommend consulting your AWS administrator prior to making this decision.

This authentication method allows you to use the ARN of an assumable role instead of hard-coded AWS access keys. When a Nintex Apps user makes a request using this authentication method, Nintex Apps makes a secure server-side request to assume the configured role. If this request is successful, Nintex Apps receives temporary access credentials, which Nintex Apps caches until the credentials expire after 60 minutes.

Requests made through an assumed role are traceable via the AWS console. From there, you can see both the Nintex Apps site and Nintex Apps user who initiated the request, which provides AWS administrators full visibility into who requested access credentials and from what Nintex Apps site.

Due to this method's security and ease-of-management after initial setup, we typically recommend it over the access keys method. However, it does require some technical knowledge to configure. Be sure to read all of the instructions below.

Before you begin

Nintex Apps can only access roles that have a defined path containing the string /Nintex Apps-assumable-role/ . This is different from the role's name. Role paths can only be set when first created, so it isn't possible to update an existing role with a new path.

In order to create a role with a path, you'll need to use either the AWS IAM API or the AWS CLI.

The instructions below assume you are using AWS CLI (version 2) and that you've already configured an access key ID and secret access key for use with the CLI. Ensure these credentials have the iam:CreateRole permission. Command line examples are also tailored for Linux or macOS operating systems; commands for command line programs on Windows may differ.

Finally, because IAM roles require a trust relationship policy upon creation, you'll need to save the JSON that Nintex Apps provides when creating an authentication provider. Because of this you'll need to navigate between your browser window, your computer's file explorer, as well as the command line.

In Nintex Apps

  1. From the Nintex Apps navigation bar, navigate to Connections > Authentication Providers.
  2. Click Create.
  3. Configure the authentication provider's basic properties:
    • Name: Enter a name, such as AWSAuth.
    • Authentication Method: AWS: Assume Role with ARN
  4. In the Trust Relationship Policy, click Copy to Clipboard.

This copied policy will enable your role to grant proper access to your Nintex Apps site.

Note: 

If you want this role to be assumable by multiple Nintex Apps sites —for example a staging site and a production site, make the sts:ExternalId property 's value into an array of Nintex Apps site Ids.

For example, change this key/value:

Copy 
"sts:ExternalId": "09583eba-de0e-49d3-ae42-61b3927a61b1"

Into this:

Copy 
"sts:ExternalId": [
   "09583eba-de0e-49d3-ae42-61b3927a61b1",
   "e354e60f-5a80-4024-b01a-4cae13d0948c"
]

Site IDs are accessible from Settings > Site > Profile.

On your local machine

  1. With the policy copied to your clipboard, paste the policy into a text editor.
  2. Save the file to an easily accessible directory (for example, your desktop) on your machine with a recognizable name and the JSON file extension, like trust-policy.json

In a command line interface

With the trust policy saved to your machine, you can now use the AWS CLI to create an assumable role.

  1. Open your command line program of choice and navigate to the directory containing your policy JSON file. For example, if you saved the file on your desktop:

    Copy 
    cd ~/Desktop

  2. Use the AWS CLI's iam create-role command to create the role with the proper path value and trust relationship policy:

    Copy 
    aws iam create-role --role-name Apps-S3-Access --path /skuid-assumable-role/ --assume-role-policy-document file://trust-policy.json

    Note:  While role-name can vary from this example, the path must contain /skuid-assumable-role/

    The CLI creates the role, outputting its ARN and other related metadata. Because of the configured path, your ARN should look similar to this: arn:aws:iam::1234567891011:role/Nintex Apps-assumable-role/Nintex Apps-S3-Access .

  3. Copy this created ARN, either from the command line output or the AWS console.

In Nintex Apps

  1. Return to the authentication provider window.
  2. Paste the copied ARN into the AWS Role ARN to assume field.
  3. Click Save.

This authentication method utilizes an Amazon Web Service (AWS) IAM role's access keys to authenticate to an AWS system.

If you are not the manager of your AWS services, follow along with Amazon's steps for creating access keys with your IT administrator. You'll need to do the following:

In AWS

  1. Create a new group and select the appropriate policies for that group.
    • These should align with your intended Nintex Apps use. Ensure your access policies match the services (S3, DynamoDB, or SNS) you'll be using.
  2. Create a new user in AWS Identity and Access Management (IAM) within the newly created group.
  3. Retrieve the access credentials generated for that user:
    • The secret access key is only displayed once, immediately after the access key is generated, and cannot be found later. Be sure to copy it to a safe place.

In Nintex Apps

With your access credentials handy, you can now use them to configure a Nintex Apps authentication provider that will work with all AWS connections.

  1. Navigate to Configure > Connections > Authentication Providers.
  2. Click New Authentication Provider.
  3. Configure the authentication provider's basic properties:
    • Name: Enter a name, such as AWSAuth.
    • Authentication Method: AWS: Access Keys
  4. Enter your IAM role's credential information:
    • AWS Access Key Id: The access key ID to use when authenticating.
    • AWS Secret Access Key: The secret access key to use when authenticating.
  5. Click Save.

Creating a Lambda connection

  1. Navigate to Connections > Connections.
  2. Click Create.
  3. Select the appropriate connection for Type.
  4. Enter an appropriate value for Name, such as AWS-ServiceName.
  5. Click Next.
  6. Select the previously configured AWS authentication provider.
  7. Select the AWS Region where the resources you need within Nintex Apps reside. See AWS documentation on regions for more information.
  8. Click Save.

After creation, leave Use proxy disabled. The proxy does not currently support these connections.

Connection-Specific Properties

Connector actions

Every Lambda function configured within the selected AWS region will be listed as a connector action. Once you select a Lambda function to invoke, you will need to configure the following properties:

  • Payload Snippet: A Nintex Apps JavaScript snippet used to construct the input payload that will be sent to, and processed by, the Lambda function.
  • Response handler Snippet: ( optional ) A Nintex Apps JavaScript snippet that processes the payload, if any, returned by the Lambda function.

Like other Nintex Apps snippets, response handler snippets may be asynchronous by returning a Promise in the snippet. Nintex Apps will wait for the Promise to be resolved before considering the Lambda function invocation to be complete.

Using the AWS Lambda Connection

Lambda is used exclusively through connector actions, available by selecting the Run Connector action action type and selecting a configured Lambda connection.

You must define and set a payload snippet to provide inputs to the Lambda function. You can optionally define a response handler snippet to handle the response from the Lambda function.

Payload snippets

A payload must always be constructed for Lambda actions, even if the function requires no input. To construct a payload, use a payload snippet to return some value. That value's data type will depend upon your function's chosen software development kit (SDK)—for example, a Python function may expect a list be returned.

For instances where you do not need input, a simple snippet will do. As an example:

Copy 
return null

Otherwise, construct a more in-depth snippet to send along the proper input. A basic example passing in model data may look like:

Copy 
var model = skuid.model.getModel('myModel'),
  firstRow = model.getFirstRow();
return firstRow.myFieldname;

This input data would then be available to the Lambda function within the event object.

A basic example of a Lambda function using data within the event object—written in a Node.JS 8.10 runtime—would look like this:

Copy 
exports.handler = async (event) => {
  const response = {
    body: "I received this input: " + event
  };
  return response;
};

This function would simply respond with a message stating the value of what was passed in by the Nintex Apps payload snippet.

Response handler snippets

If your Lambda function is returning data that will be used by models or components within the Nintex Apps page, then use a response handler snippet to parse the function's response.

Response handler snippets have access to the response sent by Lambda through arguments[0] . Reference AWS documentation for more information about the response elements.

A basic response handler snippet may look like this:

Copy 
var params = arguments[0],
  // And some variables for models if needed
  model = skuid.model.getModel('myModel'),
  firstRow = model.getFirstRow();

// To see each of the response elements
console.log(params);

// Or to log just the payload as written in the function
console.log(params.Payload);

// If the payload is a JSON object, parse it
var payload = JSON.parse(params.Payload);

// And, if applicable, update a model field with the payload's body
model.updateRow(firstRow, {ResponseFromLambda: payload.body});

Errors in Lambda functions

Note that Nintex Apps will only return an "error" if there is a problem with Nintex Apps receiving a response from Lambda, such as a network request error. Errors that come from logic within the function are considered successes by Nintex Apps since they return a response.

Ensure the function's error handling logic is within the function itself as opposed to the Nintex Apps action list. Only use Nintex Apps's on-error actions for alerting the user that a network or processing error has occurred.

Troubleshooting

  • Ensure you've selected the correct region in the connection's configuration.
  • Ensure you have the appropriate AWS secret ID and key.
  • Ensure you have the appropriate IAM permissions granted.