You may want to use master data managed by files such as XML, CSV, etc. in Questetra BPM Suite. This time, we will upload a master data file to AWS Lambda and use it as an external master for a [Search Select Box] in Questetra BPM Suite.
What is a [Search Select Box]?
The Search Select Box is a type of Data Item. When you enter a search string into the input field of the Data Item and press the search button, a selection containing the string will be displayed from the master data from which you can select and enter data.
Advantages of using a file in Lambda as an external master
If you use a file in Lambda as an external master you can handle multiple Data Items and a large amount of data with minimum configuration. For more information about how to manage master data, and the pros and cons of each method, you should refer to Several Ways to Manage Master Data with Questetra (The method introduced in this article corresponds to Pattern 1).
AWS platforms used
The method we will describe in this article uses the following services provided by AWS (Amazon Web Service). The purpose is shown in parentheses.
- Lambda (application creation)
- API Gateway (API creation)
How it works
The general framework of this mechanism is shown in the diagram below.
When the Search Select Box sends a GET request to the API Gateway, an event is sent to Lambda which searches the master data based on the event and returns the result.
Procedure overview
Together with API Gateway and Lambda we will create an API that retrieves the master data and returns the results. The master data file should be uploaded to Lambda along with the code for the Lambda function. The endpoint of the created API should be set as the URL for the Search Select Box, which lets the file in Lambda be used as the external master.
Here is a rough outline of the process.
- Download a sample Lambda function
- Edit the master file
- Create a zip file to upload to Lambda
- Create a Lambda function
- Set the API Gateway as a trigger for your Lambda Function
- Create an App that uses a search select box in Questetra BPM Suite
Procedure
1. Download a sample Lambda function
Download the sample Lambda function file from the GitHub repository here.
2. Editing the master file
The directory you downloaded in step 1 also contains a sample master file. If you wish to continue the tutorial with the sample file, please jump to step 3. If you want to rewrite the master file, please follow the next steps.
All sample master files are located in the “master” directory. Other master files should also be placed in this directory.
2-1. For XML
The file “choice-ja.xml” is a Japanese sample master file, whereas the file “choice-en.xml” is an English sample master file. If you want to change the content please refer to this page.
2-2. For CSV
The file “choice-ja.csv” is a Japanese sample master file, whereas the file “choice-en.csv” is an English sample master file. Each line represents a single choice and the choice ID and display label are separated by commas.
2-3. For TSV
The file “choice-ja.tsv” is a Japanese sample master file, whereas the file “choice-en.tsv” is an English sample master file. Each line represents one data choice, with the choice ID and display label separated by tab characters.
3. Create a zip file to upload to Lambda
Compress the directory you’ve been working in into a zip file.
3-1. For Windows
To create a zip file, right-click on all the files selected in the directory and click on “Compressed (zipped) folder” under “Send to”.
3-2. For Mac/Linux
Execute the following command in the directory
zip -r [filename].zip *For example, to compress the directory “Choices-AWS-Lambda” to create a zip file called “Lambda_function.zip”, use zip -r Lambda_function.zip *.
4. Creating a Lambda function
4-1．Create a Lambda function
Open Lambda in the AWS Management Console, select Functions from the left menu and click “Create function”.
Select “Author from scratch” and enter a function name. In our case we’ve chosen “myRdsFunction”. Select “Node.js 12.x” as the runtime and click Create Function.
4-2．Upload a .zip file
Open the Lambda function and go to “Function code”, then “Actions” in the top right corner, then “Upload a .zip file”.
Click “Upload”, select the .zip file you have created and click “Save” to upload it.
4-3．Set Environment variables
Register the file name of the file you want to use in Environment variables so that it can be read by the Lambda function.
Open “Environment variables” in the Settings tab of the Lambda function screen and click “Edit”.
On the screen that comes up click “Add environment variable, set “FILE_NAME” in the Key section and the file name of the master file you want to use in the Value section, then click “Save”.
5. Configuring the API Gateway as a trigger for Lambda functions
5-1．API Gateway Settings
Open the Lambda function and click “Add trigger” in the Designer block.
Select “API Gateway” for the trigger type, “Create an API” in the API section, “REST API” in the API type section and “Open” in the Security section. Once you have completed the configuration click Add.
Once you have added the API Gateway, make a note of its endpoint. You can check the endpoint in the Triggers section of the Lambda function’s Settings tab.
5-2．Checking how it works in your browser
Access the API Gateway endpoints with a browser to see if they work. If you see XML like the following figure, you’ve succeeded.
If you are getting an error, it’s likely that the timeout for the Lambda function is too short. See Using Amazon RDS as an External Master (Troubleshooting) and try changing the timeout setting.
Also, if the characters are garbled the master file may not be encoded in UTF-8, so please check that.
6. Creating an App with a Search Select Box in Questetra BPM Suite
Create an App in Questetra BPM Suite and add a [Search Select Box] to the Data Items (the display name is [Select (Search Select)]). In the “Type of data source” field select “Get choice list via HTTP”, enter the API Gateway endpoint you just created in the URL field and click “Apply and Close”.
Let’s release the App and check the form. Enter a search string and press the search button to see the options that match your criteria.
So that’s it. In this article we described one of the methods of using master data; using a master file uploaded to a Lambda function. On the other hand you can also use a database as an external master depending on the nature and purpose of your master data.