Table of Contents

 

Learning Objectives

 
  1. Be able to configure the Send API Request node in HAP to call APIs.
  2. Understand the API rules of Application API documentation, and build Workflows that automatically pull the Application Role List and automatically add or remove members from roles.
  3. Be able to combine nodes such as JSON Parsing, Subprocess, and PBP to flexibly handle multi-level array structures in API response data.
 

Scenario Case

 
To enable more fine-grained permission management, the Event Management application divides staff into multiple roles, including the Registration & Invitation Group, Check-in Group, Support Group, and Finance, with each role corresponding to different application permissions.
 
In the original approach, the administrator at MEGA manually added or removed users from these roles. As the number of Events increased and personnel changes became more frequent, this method became time-consuming, error-prone, and lacked a complete operation log of changes.
Therefore, they expect the application to support:
 
  1. One-click retrieval of all current roles and the users under each role, and automatically writing this information into worksheet records.
  2. In the future, driving role membership changes by filling in form records—automatically adding or removing role members, while synchronously keeping a record of all role changes for easy traceability and auditing.
 

Operation Guide

 

Requirement 1: Retrieve Current Roles and Users

 

Requirement Analysis：

 
To retrieve the current roles in the application backend and the users under each role, we need to call the “Get Role List” API of the application.
 

API Documentation Analysis：

 
First, click the dropdown button next to the application name to open the API Developer documentation, then review the requirements of the “Get Role List” endpoint, focusing on two key points:
 
 
  1. Which parameters need to be passed
 
According to the API documentation, the request must include the application authentication parameters (AppKey and Sign).
 
 
  1. What Data Is Returned by the Interface
 
According to the API documentation, the interface returns a two-level array structure:
  • The first level is a role array (containing multiple roles, each role includes role ID, role name and other information).
  • Each role object also nests a level of user array under the role (containing user ID, name and other information).
 
 

Implementation Ideas (Process Design)

 
Combined with the data structure returned by the interface, the overall implementation path can be decomposed into two-level processing:
 
1. First level: Batch Process Roles (Subprocess)
 
  • First, use the "Send API Request" node in the workflow to obtain an object array containing multiple roles.
  • Then use "Subprocess" to process each role object individually:
    • Write or update role records in the Role worksheet.
    • Continue processing the user array under the role within the subprocess.
 
2. Second level: Batch Process Users Under Roles (PBP)
 
  • In the subprocess, use the "JSON Parsing" node to extract the user array (accounts) and parameters such as accountId and user fullname from the array, then use the "Get Multiple Data" node to obtain the parsed user array.
  • Use the Packaged Business Process (PBP) to write each user in the user array to the User worksheet one by one:
    • Create or update user records.
    • Simultaneously associate the user with the current role (e.g., write role ID or role association field).
 
Through the combination of "Subprocess + JSON Parsing + PBP", we can process this complex return structure of "role array + user array under roles" in a leveled and clear manner, realizing automatic synchronization and association of roles and user.
 

Application Configuration

 

Role worksheet Configuration

 
  1. Set up the Role worksheet to store role information synchronized from the API interface, including [Role Name] and [Role ID] fields.
  2. According to actual needs, add the [Enabled] field to identify whether the current role is valid. When a historical role in the Role worksheet is no longer included in the latest synchronized role list, it can be considered that the role has been deleted, and the [Enabled] status in the system needs to be automatically updated to "Deleted".
 
 

User worksheet Configuration

 
Set up the User worksheet to store user information synchronized from the API interface, including [Account ID], Member field, and multiple associated roles.
 
 

Refresh Roles - Packaged Business Process (PBP)

 
Create a new business process named "Refresh Roles" and configure the input parameters of the packaged business process. This packaged business process is designed to be easily called on custom pages at any time, so the input parameters can be set arbitrarily, and no parameters need to be passed during actual calls.
 
 

Query User Worksheet and Batch Update

 
Add the [Get Multiple Data - Query and Batch Update] node to first clear the associated roles in the existing User worksheet to prepare for refreshing the user's role information.
 
 

Add "Send API Request" Node

 
Add a Send API Request node and select "Send Custom Request" to obtain the latest user role information of the application through the Get role list API interface.
 
 
 

Configure "Send Custom Request" Action Node

 
  1. API URL (Request Address) Configuration:
According to the application's API development documentation, select the interface call method GET and fill in the API request address.
 
 
  1. Header Configuration:
At the same time, the Header Parameters need to pass in the application's authentication parameters AppKey and Sign, which can be found in the Application Authorization tab of the API Description.
 
 
In addition, when calling other application APIs later, the authentication parameters AppKey and Sign will be used multiple times. For convenient management and direct use later, they can be set as global variables, and the global variables can be directly filled in when calling the interface.
 
 
 
After configuration, click [Test API] to test.
 
 

Obtain Role Array

 
Select the [Get Multiple Data - Get Array Object] node to obtain the array returned by the previous action node [Send API Request].
 
 
 
 

Query and Batch Update Role Worksheet

 
Query historical role records that are not in the latest roles, and update their [Enable Status] switch item to "Deleted" (i.e., disabled).
 
 
 

Refresh Roles - Subprocess "Write Role to List; Add if Not Exists"

 
Add a Subprocess node, use the role array obtained by the [Send API Request] node as the data object, configure the subprocess, and set the execution method to "Execute One by One".
 
 
The overall action node configuration of the subprocess is as follows:
  1. According to the returned role ID, query whether the role already exists in the Role worksheet. If no data is found, it indicates that the role is a newly created role and needs to be added to the Role worksheet.
  2. Use the JSON Parsing node to parse the user array (accounts) and user ID (accountId) in the user array in the subprocess.
  3. When there are users under the role, use the [Get Multiple Data - Get Array Object] node to obtain the user array from the JSON Parsing node.
  4. Call the packaged business process PBP [Write to user Worksheet] to write multiple user information in the user array to the user worksheet.
 
 
After selecting the role array obtained by [Send API Request], the array object elements passed into the subprocess are as follows:
  • accounts: user array under the role.
  • id: Role ID.
 
 

Query Role Worksheet

 
Set the filter condition to Role ID, and query whether there is a data record in the Role worksheet that is the same as the subprocess ID.
 
 
If not found, add a new record.
 
 

JSON Parsing

 
Configure the JSON Parsing node, set the object to the data object [Send API Request] of the subprocess, click "View JSON Parsing Result", then click "Generate ", and fill them into the output parameters.
 
 
 
 

Set Branch to Query Accounts Status

 
For the branch where accounts is not empty, obtain the JSON parsed array result from the previous action node [JSON Parsing] and enter the packaged business process - [Write to User Worksheet].
 
 

Configure Packaged Business Process

 
The executed data object is the JSON parsed array result in the previous [Get Array Object] node. The execution times are multiple, the method is parallel, and the input parameters are configured:
  • Required parameters: User ID (accountId), Role ID.
  • Optional parameters: User name (fullname), etc. (As long as the user is in the organization of the current application, even if the user name is not passed in, the user's account can be obtained from the organization through the user ID and filled in the Member field of the User worksheet).
 
 
 

Refresh Roles - PBP (Write to User Worksheet)

 
The overall process configuration is as follows:
  • Query the corresponding role record from the Role worksheet according to the Role ID.
  • Query the corresponding account information from the organization according to the User ID.
  • Query whether there is a corresponding record in the User worksheet according to the User ID. If not, add a new user record.
  • Finally, update the role association field in the User worksheet to add the current role record for the user.
 
 

Query Role Worksheet Records

 
Query the corresponding role record from the Role worksheet according to the input parameter Role ID of the packaged business process.
 
 

Query User Information from the Organization According to User ID

 
Use the [Get Single Personnel] node to query the corresponding user information from the organization according to the input parameter accountId of the packaged business process, which is used to fill in the Member field when adding a new user record later.
 
 

Query User Worksheet Records; Add if Not Exists

 
Query whether the user exists in the User worksheet according to the accountId. If not found, add a new user and fill in the Member and Account ID.
 
 
 

Update the Role Associated with the User Worksheet to Add the Current Role

 
Use the Update Record node to add the currently obtained role record to the role associated with the User worksheet.
 
 

Publish Process

 
After all configurations are completed, publish the three-level workflows of "Refresh Roles", "Write the Role to the List", and "Write to User Worksheet" respectively.
 

Custom Page Button Calls "Refresh Roles" PBP

 
On the custom page "Refresh Roles", add a button "Pull Application Roles List" and set it to call the packaged business process "Refresh Roles" when clicked.
 
 
 

Implementation Effect

 
On the "Refresh Roles" custom page, after clicking the "Pull Application Roles List" button, the workflow will automatically pull the application's roles and users under the roles, realizing:
 
  1. Write role data to the Role worksheet.
 
 
  1. Write user data to the User worksheet, and simultaneously write the association information of their affiliated roles in the user records.
 

Requirement 2: Automation of Adding/Removing Users Under Roles

 

Requirement Analysis

 
  1. When adding a user to a role, the "Add role members" interface needs to be called; when removing a user from a role, the "Remove role members" interface needs to be called.
  2. At the same time, to ensure data consistency between the front and back ends, after calling the interface to add or remove a member from an application role, the front-end Role worksheet and User worksheet also need to be automatically changed accordingly.
 

API Documentation Analysis

 
In this requirement, we only care about the execution result of "User addition/removal" and do not need to process the data returned by the interface. Therefore, the focus is to clarify what parameters need to be passed into the interface. The core parameters include:
  1. Application authentication parameters: AppKey, Sign.
  2. Business parameters: Role ID, User ID collection (multiple users can be passed at one time).
 
 

Implementation Ideas

 
  1. Establish a Personnel Role Change worksheet to register the addition and withdrawal operations of User under roles.
    1. For user-friendliness, if it is "Exit Role", the "Exit Role" operation can be initiated in the change Worksheet by selecting an existing user and then their affiliated role.
  2. After the change record takes effect, according to the change type (Join/Exit), respectively:
    1. Call the "Join Role" or "Exit Role" interface to complete the adjustment of back-end role members.
    2. Simultaneously automatically update the user's affiliated role field in the front-end User worksheet, add or remove the corresponding role to ensure data consistency, and form clear change traces.
 

Application Construction

 

Role Change Worksheet Configuration

 
Desired filling effect:
 
  1. When the application type is "Join Role", directly select members and the role to be changed. The role to be changed can be any role under the current application.
 
 
  1. When the application type is "Exit Role", first select the user to withdraw from the User worksheet, and then the optional range of Role to be changed will be limited to one of the roles that the user currently belongs to.
 
 

Configure Business Rules

 
Set business rules: When [Application Type] is "Exit Role", display User (Associated Record) and Existing Role (Associated Record).
 
 

Set Default Values

 
Set the default value of the [Existing Role] field to automatically bring out the roles belonging to the current user.
 
 
And Set the default value of the "Change Member" field to the member account in the associated user.
 
 

Set Associated Record Selection Range

 
Set the selection range of the associated record of the role to be changed, set the condition as [Record ID = Existing Role], and set "Ignore this condition when the dynamic value used by the condition is empty (return all records when all are ignored)".
 
Through this configuration: When the user withdraws from a role, they can only select from the exsiting roles; when the user joins a role, they can select all roles.
 
 
 

Set Workflow for the "Apply" Button

 
 

Overall Process Logic

 
The overall logic of the "Apply" button workflow is as follows:
  1. Obtain the role to be changed associated with the change order, i.e., the role to be added/withdrawn from.
  2. Obtain personnel information from the member field of the change order.
  3. Determine the application type of the change order.
    1. If the application type is "Join Role":
      1. Call the "Join Role" interface.
      2. Update the status of the role change order to "Effective".
      3. Query whether the changed member exists in the User worksheet. If not, add a new user record.
      4. Add the current changed role to the associated field of the user's affiliated roles.
    2. If the application type is "Exit Role":
      1. Call the "Exit Role" interface.
      2. Update the status of the role change order to "Effective".
      3. Obtain the User worksheet associated with the change order (the user association field is required when withdrawing from a role).
      4. Subtract the current changed role from the associated field of the user's affiliated roles.
 
 

Obtain the Role Associated with the Change Order

 
 

Obtain Personnel Information from the Change Member Field of the Change Order

 
Through the [Get Single Personnel] node, obtain personnel information from the Change Member field, which can get the user ID information of the personnel, for use when adding a new User worksheet record later.
 
 

Logic for Adding to a Role

 
Call the "Add role members" Interface:
When the application type = "Join Role", call the "Join Role" API interface through the [Send API Request] node and pass in the corresponding parameters of the interface.
 
 
Update the Effective Status of the Personnel Role Change to "Effective".
 
 
Query the changed user; add if not exists:
Query whether the currently changed user exists in the User worksheet through the member field. If no data is found, add a new user record and fill in the Member and User ID.
 
 
 
Update the associated role of the User worksheet to add the currently changed user.
 
 

Logic for Exiting from a Role

 
Call the "Remove role members" Interface: When the application type = "Exit Role", call the "Exit Role" API interface through the [Send API Request] node and pass in the corresponding parameters of the interface.
 
 
Update the effective status of the change order to "Effective".
 
 
Query the user associated with the change order:
When the application type is "Exit Role", the user association record of the change order is required, so the changed User record can be directly obtained by means of getting associated records.
 
 
Update the associated role of the User worksheet to remove the currently changed role.
 
 

Implementation Effect

 
As shown in the figure, this member has joined three roles in the background: Developer, Administrator, and Operator.
 
 
Create a change order and select to withdraw from the Operator role.
 
 
After clicking the "Apply" button, the member will be automatically removed from the back-end Operator role, and the association between the user and the Operator role will be cleared in the User worksheet.
 
 
 
 
 

Hands-on Practice

 
Now, click the "Open the Practice App" button in the upper right corner of the page to access the hands-on application designed for this course, and start practicing!