User provisioning application in Jitterbit App Builder

Introduction

This page shows you how to create a user provisioning application that front-end users can use to provision application access in a semi-automated way, without needing access to the IDE. This is an alternative approach to managing user access when an identity provider (such as Okta or Azure) is not available.

The process involves creating security providers, configuring realms, preparing the data model, building a sequence of business rules to handle the logic, and creating a simple UI for front-end users to trigger the process.

These instructions use the example of providing a company's employees with access. The instructions are divided into five steps:

• Step 1: Initial configuration

• Step 2: Configure access control

• Step 3: Prepare the data model

• Step 4: Build the provisioning model

• Step 5: Create the user interface

Preparation

To start, create a dedicated app to provision users. The one used in this tutorial is called simply User Provisioning App and starts with the following tables:

Additional columns are added to these tables during the steps below.

Step 1: Initial configuration

First, you need a security provider to handle the provisioning, and a place to store its configuration details.

Create a security provider

To create a security provider, follow these steps:

1. Select IDE > Security Providers.

2. Under User Authentication, click + User Authentication.

3. Configure the provider with these settings:

   • Name: User Provisioning

     Note

     Not to be confused with the provisioning app itself, which is called User Provisioning App.

   • Type: User Provisioning

   • Enabled: Checked.

   • User Provisioning: Checked.

4. Click Save.

5. Copy and save the new provider's Identifier key for the next step.

Parameterize the configuration

To store the provider ID and a default password in your application's Parameter table, follow these steps:

1. Run your user provisioning app, then go to the App Workbench Tables tab.

2. Under Tables, find the Parameter table, then click its Open record icon.

3. Add the following two columns:

   • MyProviderID (Type: Unique ID)

   • DefaultPassword (Type: String)

4. Go to the App Workbench Pages tab.

5. Under Pages, find the Parameter page, then click its icon.

6. Add new controls (control type Text) to the page for the MyProviderID and DefaultPassword columns.

7. Run the application and select Configuration > Parameters. The Parameters popup opens.

8. Click Edit.

9. Paste the security provider identifier (copied earlier) into the MyProviderID field.

10. Enter a secure default password in the DefaultPassword field. This is the password that is assigned to new users.

11. Click Save, then close the Parameter popup.

Step 2: Configure access control

With the provider created, you can now configure the user groups and realms that govern access. To do this, follow these steps:

1. Select IDE > User Management.

2. Select the Groups tab.

3. Click + Group. The Group popup opens.

4. Set the following values:

   • Name: Demo General User

   • Description: General user permissions for the demo app.

5. Click Save, then close the Group popup.

6. Under Groups, click Manage Privileges for the new group.

7. Under Privileges, click Create. The Privilege popup opens.

8. Set the following values:

   • Type: Select Application.

   • Application: Open the menu and select the app that end users will access.

   Note

   The app you should select here is the one that end users will log in to. This may or may not be the provisioning app itself. In this tutorial, a dedicated provisioning app was built to manage access to one or more apps, therefore you should select the target app here, not the provisioning app.

9. Click Save, then close the Privileges/Roles panel.

10. Under Roles, grant the appropriate roles for general users.

11. Select the Realms tab.

12. Click + Realm.

13. Enter Demo Realm as the name, then click the icon.

14. In the Applications tab, click Select for the app that end users will access.

15. Select the Groups tab, then click Select for the Demo General User group just created.

16. Select the Providers tab, then click Select for the User Provisioning security provider created earlier.

Step 3: Prepare the data model

Now you must update your Department and Employee tables to store security information and provisioning status.

Link Departments to security groups

Follow these steps:

1. With your app running, go to the App Workbench Data Sources tab.

2. Click + Source.

3. Select Link to existing source, then click Next.

4. Find and select App Builder (Sealed) (Default), then click Link 1 Source and Done. This gives you access to public data objects needed for provisioning.

5. Go to the App Workbench Tables tab.

6. Under Tables, find the Department table, then click its Open record icon.

7. Add a new column named MyGroupID (Type: Unique ID).

8. Go to the App Workbench Pages tab, then open your Department page for editing.

9. Add the MyGroupID control to your page. Set its Control Type to List, then click Next.

10. On the next page, set these values, then click Next:

    • Source: Realm_Group

    • Key (Column): GroupId (PK)

    • Title (Column): Name

11. Click Finish.

12. Go to the App Workbench Pages tab, then open your Department page for editing.

13. Select the Update Methods tab.

14. Ensure the Edit Method setting is Standard.

15. Run the application, navigate to the Departments page, and assign the Demo General User group to one of your departments.

Update the Employee table

Follow these steps:

1. Go to the App Workbench Tables tab.

2. Under Tables, find the Employee table, then click its Open record icon.

3. Add the following columns:

   • MyUserID (Type: Unique ID): Stores the user's App Builder ID after creation.

   • ProvisionedOn (Type: DateTime): A timestamp for when provisioning occurred.

   • ProvisionedBy (Type: String, length: 150): The name of the user who performed the provisioning.

Step 4: Build the provisioning logic

The core of the application is a table-level event on the Employee table that orchestrates a sequence of rules. These rules run one after another using success handlers.

Rule 1: Create the user

This rule creates the user record, but only if one does not already exist. Follow these steps:

1. Go to the App Workbench Tables tab.

2. Under Tables, find the Employee table, then click its Open record icon.

3. Click Events. The Data Storage Events (Employee) popup opens.

4. Click + Table Event.

5. Under Event Information, set the Name as Provision User, then click Save.

6. Under Actions, click + Rule & Register.

7. On the Rule Builder page, set the following values:

   • Name: Realm_User_Create (Insert Employee)

   • Purpose: XP CRUD

   • Action: Insert

   • Source Data Source: Select the user provisioning app you've created. In this tutorial, it's User Provisioning App.

   • Target Data Source: Vinyl (Sealed)

   • Options: Select Logic Layer.

   • Target: Realm_User_Create

8. Click Create.

9. With the Tables tab selected, click + Table.

10. In the Current Data Source tab, add the Employee table.

11. Select the Where tab.

12. Click + Where Clause.

13. Under Left Expression, enter E.MyUserID.

14. Open the Operator menu, then select IS NULL.

15. Click Save, then close the Where popup.

16. Select the Tables tab, then select EmployeeID and any additional columns the rule needs for its action (for example, the provisioned user's name and email address).

17. Select the Columns tab, and set fields as follows:

    Column or Expression	Alias	Target	PK
    E.EmployeeID		UserId (PK)
    E.FullName		FullName
    E.Email		EmailAddress
    E.FullName	DisplayName	DisplayName
    E.EmployeeNo	UserName	UserName

18. (Optional, but recommended) Select the Results tab and click Validate.

19. Go to the App Workbench Tables tab.

20. Under Tables, find the Employee table, then click its Open record icon.

21. Click Events. The Data Storage Events (Employee) popup opens.

22. Click the Open record icon for the Provision User event.

23. Under Actions, click the Open record icon for the Realm_User_Create (Insert Employee) rule.

24. Under Bindings, click + Binding.

25. Set the following binding:

    Source Column	Rule Column
    EmployeeID	EmployeeID

26. Click the icon, then close the Action/Bindings/SQL popup.

Rule 2: Update the employee record

After the App Builder user is created by Rule 1, this rule writes the new user's ID back into the MyUserID field on the Employee table. This links the employee record to their App Builder account so that subsequent rules can reference their ID.

1. On the Event/Validations/Actions page, under Actions, click + Rule & Register.

2. Set the following values:

   • Name: Employee (Update MyUserID to EmployeeID)

   • Purpose: CRUD

   • Action: Update

   • Target Layer: Data Layer

   • Target: Employee

3. Click Create.

4. Select the Columns tab.

5. Click + Column.

6. In the Column or Expression box, enter E.EmployeeID, then set these remaining values:

   • Alias: MyUserID

   • Target: MyUserID

   • TargetType: Target

7. Click Save, then close the Add Column popup.

8. (Optional, but recommended) Select the Results tab and click Validate.

9. Click < Event to return to the Provision User page (Event/Validations/Actions).

10. Under Actions, click to deregister the just added and registered rule (Employee (Update MyUserID to EmployeeID)), then click Proceed.

11. Under Actions, click the Open record icon for the remaining Realm_User_Create (Insert Employee) action. The Action/Bindings/SQL popup opens.

12. Click Success. The Success Handlers popup opens.

13. Click Create. The Action popup opens.

14. Set the following values:

    • Type: Rule

    • Rule: Select Employee (Update MyUserID to EmployeeID)

15. Click Save.

16. Under Bindings, click + Binding.

17. Set the following binding:

    Source Column	Rule Column
    EmployeeID	EmployeeID

18. Close the popups to return to the Event/Validations/Actions page for Provision User.

    Tip

    The number 1 next to the icon indicates the presence of a success handler for this action.

Rule 3: Set the user password

This rule sets the new user's initial password using the default value stored in the Parameter table.

1. Go to the App Workbench Rules tab.

2. Click + Rule.

3. Set the values as follows:

   • Name: User_SetPassword (Update Default Password)

   • Purpose: Select XPCRUD

   • Action: Update

   • Source Data Source: Select the user provisioning app you've created. In this tutorial, it's User Provisioning App.

   • Target Data Source: Vinyl (Sealed)

   • Target Layer: Logic Layer

   • Target: User_SetPassword

4. Click Create.

5. Select the Tables tab.

6. In the Current Data Source tab, click + Table, then add the Employee and Parameter tables.

7. In the Employee table, select the EmployeeID and MyUserID columns.

8. In the Parameter table, select the DefaultPassword column.

9. Select the Columns tab, and set fields as follows:

   Column or Expression	Alias	Target	PK
   E.MyUserID		UserID (PK)
   P.DefaultPassword		Password

10. (Optional) Click the Open record icon for the E.MyUserID column. In the Column popup, confirm that the Target Type is Bind.

11. (Optional) Click the Open record icon for the P.DefaultPassword column. In the Column popup, confirm that the Target Type is Target.

12. Select the Where tab, then click + Where Clause.

13. Under Left Expression, enter E.MyUserID.

14. Open the Operator menu, then select IS NOT NULL.

15. Click Save, then close the Where popup.

16. Go to the App Workbench Rules tab.

17. Under App Data Sources, select All Events.

18. Under All Events, click Provision User in the Event column.

19. For the Provision User entry, click Rule Event Detail.

20. Under Actions, click the Success handlers icon for the Realm_User_Create (Insert Employee) rule. The Success Handlers popup opens.

21. Click Create. The Action popup opens.

22. Set the following values:

    • Type: Rule

    • Rule: Select User_SetPassword (Update Default Password)

23. Click Save.

24. Under Bindings, click + Binding.

25. Set the following binding:

    Source Column	Rule Column
    EmployeeID	EmployeeID

26. Close the popups to return to the Event/Validations/Actions page for Provision User.

27. Refresh the page, and note the number of success handlers for the Realm_User_Create (Insert Employee) rule is now 2.

Rule 4: Grant group access

This rule grants the new user access to the App Builder group associated with their department, using the MyGroupID value set in the Department table.

1. Go to the App Workbench Rules tab.

2. Click + Rule.

3. Set the values as follows:

   • Name: Realm_UserGroup (Cram Department)

   • Purpose: Select XPCRUD

   • Action: Cram

   • Source Data Source: Select the user provisioning app you've created. In this tutorial, it's User Provisioning App.

   • Target Data Source: Vinyl (Sealed)

   • Target Layer: Logic Layer

   • Target: Realm_UserGroup

4. Click Create.

5. Select the Tables tab.

6. In the Current Data Source tab, click + Table, then add the Employee and Department tables.

   Tip

   App Builder automatically creates a foreign key relationship between the two tables' DepartmentID columns.

7. In the Employee table, select the EmployeeID and MyUserID columns.

8. In the Department table, select the MyGroupID column.

9. Select the Where tab, then click + Where Clause.

10. Under Left Expression, enter D.MyGroupID.

11. Open the Operator menu, then select IS NOT NULL.

12. Click Save, then close the Where popup.

13. Click + Where Clause.

14. Under Left Expression, enter E.MyUserID.

15. Open the Operator menu, then select IS NOT NULL.

16. Click Save, then close the Where popup.

17. Select the Columns tab, and set fields as follows (for example):

    Column or Expression	Alias	Target	PK
    E.EmployeeID
    E.MyUserID		UserID (PK)
    D.MyGroupID		GroupID (PK)

18. Select More > Edge Case. The Edge Case Settings popup opens.

19. Enable the Select Distinct option, then close the popup.

20. Go to the App Workbench Rules tab.

21. Under App Data Sources, select All Events.

22. Under All Events, click Provision User in the Event column.

23. For the Provision User entry, click Rule Event Detail.

24. Under Actions, click the Open record icon for the Realm_User_Create (Insert Employee) rule.

25. Click Success. The Success Handlers popup opens.

26. Click Create. The Action popup opens.

27. Set the following values:

    • Type: Rule

    • Rule: Select Realm_UserGroup (Cram Department)

28. Click Save.

29. Under Bindings, click + Binding.

30. Set the following binding:

    Source Column	Rule Column
    EmployeeID	EmployeeID

31. Close the popups to return to the Event/Validations/Actions page for Provision User.

Rule 5: Log the provisioning action

This rule records who triggered the provisioning and when, by writing the current timestamp and the logged-in user's name to the ProvisionedOn and ProvisionedBy fields on the Employee table.

1. Go to the App Workbench Rules tab.

2. Click + Rule.

3. Set the following values:

   • Name: Employee (Update ProvisionedOn/By)

   • Purpose: CRUD

   • Action: Update

   • Target Layer: Data Layer

   • Target: Employee

4. Click Create.

5. Select the Columns tab.

6. Click + Column.

7. In the Column or Expression box, enter now(), then set these remaining values:

   • Target: ProvisionedOn

   • TargetType: Target

8. Click Save, then close the Add Column popup.

9. Click + Column.

10. In the Column or Expression box, enter who(), then set these remaining values:

    • Target: ProvisionedBy

    • TargetType: Target

11. Click Save, then close the Add Column popup.

12. (Optional, but recommended) Select the Results tab, then click Validate.

13. Go to the App Workbench Rules tab.

14. Under App Data Sources, select All Events.

15. Under All Events, click Provision User in the Event column.

16. For the Provision User entry, click Rule Event Detail.

17. Under Actions, click the Success handlers icon for the Realm_User_Create (Insert Employee) rule. The Success Handlers popup opens.

18. Click Create. The Action popup opens.

19. Set the following values:

    • Type: Rule

    • Rule: Select Employee (Update ProvisionedOn/By)

20. Click Save.

21. Under Bindings, click + Binding.

22. Set the following binding:

    Source Column	Rule Column
    EmployeeID	EmployeeID

23. Close the popups to return to the Event/Validations/Actions page for Provision User.

Step 5: Create the user interface

1. Navigate to Pages and open your Employee page for editing.

2. Add a new Button control with the label Provision User.

3. In the button's properties, navigate to the Events tab and select the Provision User event.

4. To ensure the UI updates correctly, in the Behavior tab, set the Refresh Scope to Row.

5. To hide the button for already-provisioned users, go to the Visibility tab and add a condition: ProvisionedOn IS NOT NULL.

Next steps

The core provisioning logic is now complete. You can enhance this process further by:

• Adding a workflow event to email new users their login credentials (see Email in Notifications).

• Using other public data objects to require a password change on first login (see User_LocalAuthentication public data object).

• Expanding the rule set to handle de-provisioning users (see Realm_UserGroup public data object).