--- title: Custom request type with form workflow example description: In this example, an administrator wants to create a custom request type called Create New User to add new employees or contractors to the system. Administrators or form creators need to carry out the following tasks: component: pingoneaic page_id: pingoneaic:identity-governance:administration/example-workflow-custom-request-type-with-form canonical_url: https://docs.pingidentity.com/pingoneaic/identity-governance/administration/example-workflow-custom-request-type-with-form.html keywords: ["workflows", "use cases", "examples", "forms", "custom request type"] section_ids: assumptions: Assumptions example: Example create-custom-request-type: "Task 1: Create a custom request type" create-form-for-custom-request-type: "Task 2: Create a form for the custom request type" create-form-using-ui: Using the admin console create-form-using-api: Using the API create-workflow-with-custom-request-type: "Task 3: Create a workflow to use the custom request type and form" submit-the-custom-request: "Task 4: Submit the custom request" approver-task-process-the-request: "Approver Task: Process the request" --- # Custom request type with form workflow example In this example, an administrator wants to create a custom request type called `Create New User` to add new employees or contractors to the system. Administrators or form creators need to carry out the following tasks: * [Create a custom request type](#create-custom-request-type). * [Create a simple form for the new custom request type](#create-form-for-custom-request-type). * [Create a workflow to handle the custom request type and the form](#create-workflow-with-custom-request-type). * [Submit a request](#submit-the-custom-request). After these tasks, the approver receives the request and can start [processing the approval](#approver-task-process-the-request). ## Assumptions * Each application has an application owner. An application owner is a user identity designated to manage the application. You populate this value for each target application. * You have designated an end user or a test user who can approve the request. * You have configured notifications to the end user or test user to receive the emails. ## Example ### Task 1: Create a custom request type The initial task is to create a custom request type, `Create New User` that lets an administrator add a new user to the system. The `Create New User` request type has the following nonmodifiable properties: * userName. Username of the new user. * givenName. First name of the new user. * sn. Last name of the new user. * mail. Email address of the new user. 1. Create a custom request type called `createUser` using the API. Enter the following command using curl to create your custom request type: > **Collapse: Details** > > ``` > curl --location 'http:///iga/governance/requestTypes' \ > --header 'Authorization: Bearer ' \ > --header 'Content-Type: application/json' \ > --data '{ > "id": "createNewUser", > "schemas": { > "custom": [ > { > "_meta": { > "type": "system", > "displayName": "Create User", > "properties": { > "userName": { > "isRequired": true, > "isInternal": false, > "isMultiValue": false, > "display": { > "name": "User Name", > "isVisible": true, > "order": 1, > "description": "The userName of the new user" > } > }, > "givenName": { > "isRequired": true, > "isInternal": false, > "isMultiValue": false, > "display": { > "name": "First Name", > "isVisible": true, > "order": 2, > "description": "The first name of the new user" > } > }, > "sn": { > "isRequired": true, > "isInternal": false, > "isMultiValue": false, > "display": { > "name": "Last Name", > "isVisible": true, > "order": 3, > "description": "The last name of the new user" > } > }, > "mail": { > "isRequired": true, > "isInternal": false, > "isMultiValue": false, > "display": { > "name": "Email Address", > "isVisible": true, > "order": 4, > "description": "The email address of the new user" > } > } > } > }, > "properties": { > "userName": { > "type": "text" > }, > "givenName": { > "type": "text" > }, > "sn": { > "type": "text" > }, > "mail": { > "type": "text" > } > } > } > ] > }, > "workflow": { > "id": "createNewUser", > "type": "bpmn" > }, > "validation": { > "source": "var validation = {\"errors\" : [], \"comments\" : []}; if (request.custom.userName == undefined || request.custom.givenName == undefined || request.custom.sn == undefined || request.custom.mail == undefined) { validation.errors.push(\"Must include all of userName, givenName, sn, and mail fields.\");} validation;" > }, > "custom": true, > "displayName": "Create User", > "uniqueKeys": [ > "custom.userName" > ], > "notModifiableProperties": [] > }' > ``` ### Task 2: Create a form for the custom request type You have two options to create a form for a custom request type: use [the UI](#create-form-using-ui) or [the API](#create-form-using-api). #### Using the admin console 1. In the Advanced Identity Cloud admin console, click Governance > Forms. 2. In the New Form modal, click Custom request form, and then click Next. 3. In the Custom request form modal, enter the following: | Field | Description | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Form | Enter a descriptive name for your form. | | Description (optional) | Enter a general description for your form. | | Request Type (optional) | Select a custom request type from the list. In this example, select Create User. You can only assign one form to each request type. | | Use this form for request creation | Click this option to make this form available to the end user when creating new requests of this request type. If unchecked, the request type only provides form field key suggestions during the form design process. For this example, leave this checkbox unchecked. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | After you create your form, you can go back and make edits to any of the previous form settings by clicking the ellipsis([icon: more_horiz, set=material, size=inline]) in the top right, and then click Settings. | 4. Use the Forms editor to create a form for your custom request type. For example, drag-and-drop four text fields onto the canvas for the fields and label them: `User Name`, `E-mail address`, `First Name`, and `Last Name`. 1. On the Forms editor canvas, drag-and-drop the Text node to the canvas, and fill in the properties in the right pane for the `User Name` field: > **Collapse: User name text field properties** > > | Field | Description | > | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | Key | Enter the key for the text string. You can retrieve this key from the [curl step](#create-custom-request-type) under the `schemas` entry. For example, enter `custom.userName` as the key. | > | Label | Enter a general label for this text field. For example, enter `User Name`. | > | Description | Enter help text for the text field. The description appears below your text field. | > | Required | Click if this text field is required. In this example, click Required. | > | Read Only | Click to make the field non-editable. | > | Provide Default Value | Click Provide Default Value to assign a default value for this text field. In this example, skip this step. | > | Columns | Enter the number of columns for this text field. Values are from 1 to 12. For this example, enter `6`. | > | Offset | Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, enter `0`. | > | Use validation | Click if you want to validate the text field using a regular expression. In this example, skip this step. | > | Regex | Enter a regular expression to validate the text field. | > | Error message | Enter an error message when the regular expression fails. | 2. On the Forms editor canvas, drag-and-drop the Text node to the canvas, and fill in the properties in the right pane for the `E-mail address` field: > **Collapse: E-mail address text field properties** > > | Field | Description | > | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Key | Enter the key for the text string. You can retrieve this key from the [curl step](#create-custom-request-type) under the `schemas` entry. For example, enter `custom.mail` as the key. | > | Label | Enter a general label for this text field. For example, enter `E-mail address`. | > | Description | Enter help text for the text field. The description appears below your text field. | > | Required | Click if this text field is required. In this example, click Required. | > | Read Only | Click to make the field non-editable. | > | Provide Default Value | Click Provide Default Value to assign a default value for this text field. In this example, skip this step. | > | Columns | Enter the number of columns for this text field. Values are from 1 to 12. For this example, enter `6`. | > | Offset | Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, enter `0`. | > | Use Validation | Click if you want to validate the text field using a regular expression. In this example, skip this step. | > | Regex | Enter a regular expression to validate the text field. | > | Error message | Enter an error message when the regular expression fails. | 3. On the Forms editor canvas, drag-and-drop the Text node to the canvas, and fill in the properties in the right pane for the `First Name` field: > **Collapse: First name text field properties** > > | Field | Description | > | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Key | Enter the key for the text string. You can retrieve this key from the [curl step](#create-custom-request-type) under the `schemas` entry. For example, enter `custom.givenName` as the key. | > | Label | Enter a general label for this text field. For example, enter `First Name`. | > | Description | Enter help text for the text field. The description appears below your text field. | > | Required | Click if this text field is required. In this example, click Required. | > | Read Only | Click to make the field non-editable. | > | Provide Default Value | Click Provide Default Value to assign a default value for this text field. In this example, skip this step. | > | Columns | Enter the number of columns for this text field. Values are from 1 to 12. For this example, enter `6`. | > | Offset | Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, enter `0`. | > | Use validation | Click if you want to validate the text field using a regular expression. In this example, skip this step. | > | Regex | Enter a regular expression to validate the text field. | > | Error message | Enter an error message when the regular expression fails. | 4. On the Forms editor canvas, drag-and-drop the Text node to the canvas, and fill in the properties in the right pane for the `Last Name` field: > **Collapse: Last name text field properties** > > | Field | Description | > | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | Key | Enter the key for the text string. You can retrieve this key from the [curl step](#create-custom-request-type) under the `schemas` entry. For example, enter `custom.sn` as the key. | > | Label | Enter a general label for this text field. For example, enter `Last Name`. | > | Description | Enter help text for the text field. The description appears below your text field. | > | Required | Click if this text field is required. In this example, click Required. | > | Read Only | Click to make the field non-editable. | > | Provide Default Value | Click Provide Default Value to assign a default value for this text field. In this example, skip this step. | > | Columns | Enter the number of columns for this text field. Values are from 1 to 12. For this example, enter `6`. | > | Offset | Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, enter `0`. | > | Use validation | Click if you want to validate the text field using a regular expression. In this example, skip this step. | > | Regex | Enter a regular expression to validate the text field. | > | Error message | Enter an error message when the regular expression fails. | 5. Click Save. ![An example of a form for the \`Create User\` custom request type.](../_images/governance-forms-custom-request-example.png) #### Using the API 1. Enter the following curl command to create your form for the custom request type: > **Collapse: Details** > > ``` > curl --location 'http:///iga/governance/requestForms' \ > --header 'Authorization: Bearer ' \ > --header 'Content-Type: application/json' \ > --data '{ > "name": "Create New User", > "type": "request", > "description": "Form for creation of a new user", > "categories": { > "applicationType": null, > "objectType": null, > "operation": "create" > }, > "form": { > "fields": [ > { > "id": "dd155b12-fb27-44e5-b4d6-476587b31a71", > "model": "custom.userName", > "type": "string", > "label": "User Name", > "description": "User name of the new user", > "validation": { > "required": true > }, > "layout": { > "columns": 6, > "offset": 0 > } > }, > { > "id": "88c73e69-86b1-453f-878b-527ceddeccf4", > "model": "custom.mail", > "type": "string", > "label": "E-mail address", > "description": "E-mail address of the new user", > "validation": { > "required": true > }, > "layout": { > "columns": 6, > "offset": 0 > } > }, > { > "id": "683892f9-2c13-41c7-a1cc-fcf38d7d0183", > "model": "custom.givenName", > "type": "string", > "label": "First Name", > "description": "First name of the new user", > "validation": { > "required": true > }, > "layout": { > "columns": 6, > "offset": 0 > } > }, > { > "id": "76fd5526-2ade-42a9-9b03-b6899e65aa31", > "model": "custom.sn", > "type": "string", > "label": "Last Name", > "description": "Last name of the new user", > "validation": { > "required": true > }, > "layout": { > "columns": 6, > "offset": 0 > } > } > ] > } > }' > ``` 2. Enter the following curl command to assign the form to the custom request type. > **Collapse: Details** > > ``` > curl --location 'http:///iga/governance/requestFormAssignments?_action=assign' \ > --header 'Authorization: Bearer ' \ > --header 'Content-Type: application/json' \ > --data '{ > "formId": "b309b500-112c-4e6d-b832-a902f91362a3", > "objectId": "requestType/createNewUser" > }' > ``` ### Task 3: Create a workflow to use the custom request type and form Create a new workflow called `Create New User` to use the custom request type and form. ![An example of a workflow using the organization request type and form.](../_images/governance-workflow-custom-request-example.png) * 1 Use a Script node to do a context check for the request. > **Collapse: Click to display the Request Context Check script** > > ```js > var content = execution.getVariables(); > var requestId = content.get('id'); > var context = null; > var skipApproval = false; > try { > var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {}); > if (requestObj.request.common.context) { > context = requestObj.request.common.context.type; > if (context == 'admin') { > skipApproval = true; > } > } > } > catch (e) { > logger.info("Request Context Check failed "+e.message); > } > > logger.info("Context: " + context); > execution.setVariable("context", context); > execution.setVariable("skipApproval", skipApproval); > ``` * 2 Use an IF/ELSE node and name it `Context Gateway`. If `skipApproval==true`, route it to the `Auto Approval` node. If `skipApproval==false`, route it to the `Approval Task` node. * 3 Use a Script node for the `Auto Approval` task. > **Collapse: Click to display the Auto Approval script** > > ```js > var content = execution.getVariables(); > var requestId = content.get('id'); > var context = content.get('context'); > var queryParams = { > "_action": "update" > } > try { > var decision = { > "decision": "approved", > "comment": "Request auto-approved due to request context: " + context > } > openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams); > } > catch (e) { > var failureReason = "Failure updating decision on request. Error message: " + e.message; > var update = {'comment': failureReason, 'failure': true}; > openidm.action('iga/governance/requests/' + requestId, 'POST', update, queryParams); > > } > ``` * 4 Use a Script node to create a new user using the custom request type. > **Collapse: Click to display the Create User script** > > ```js > logger.info("Creating User"); > > var content = execution.getVariables(); > var requestId = content.get('id'); > var failureReason = null; > > try { > var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {}); > logger.info("requestObj: " + requestObj); > } > catch (e) { > failureReason = "Provisioning failed: Error reading request with id " + requestId; > } > > if(!failureReason) { > try { > var request = requestObj.request; > var payload = { > "userName": request.custom.userName, > "givenName": request.custom.givenName, > "sn": request.custom.sn, > "mail": request.custom.mail, > "password": 'DemoP@ssword1' > }; > > /** Create new user **/ > var result = openidm.create('managed/alpha_user', null, payload, queryParams); > > /** Send new user email **/ > var body = { > subject: "Welcome " + payload.givenName + " " + payload.sn + "!", > to: payload.mail, > body: "Your new user has been created in the system.\n\nUsername: " + payload.userName + "\nPassword: " + payload.password + "\n\nLogin to your account here: https://openam-gov-dev-4.forgeblocks.com/am/XUI/?realm=/alpha#/", > object: {} > }; > openidm.action("external/email", "send", body); > } > catch (e) { > failureReason = "Creating user failed: Error during creation of user " + request.custom.userName + ". Error message: " + e.message; > } > > var decision = {'status': 'complete', 'decision': 'approved'}; > if (failureReason) { > decision.outcome = 'not provisioned'; > decision.comment = failureReason; > decision.failure = true; > } > else { > decision.outcome = 'provisioned'; > } > > var queryParams = { '_action': 'update'}; > openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams); > logger.info("Request " + requestId + " completed."); > } > ``` * 5 The Approval node assigns an approval task to users and roles. The node chains tasks in conjunction with a Switch node to implement serial or parallel flows. > **Collapse: Click to display the Approval Task properties** > > | Item | Description | > | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Name | `Approval Task` | > | Approvers | Two options are available:- Add users and roles manually, such as `Role Owner`, and define the `Approver` type. For this example, click [icon: add, set=material, size=inline]. In the Approver Type field, select User, and then select a user. Give the approvers the permissions below. Click Add. > > * Approve > > * Reject > > * Forward > > * Modify > > * Comment > > - Define users using a script: | > | Form | Select a form to present to the reviewer.- Dynamic form selection. Skip this step > > - Click Choose a form and select `Create New User`. | > | Expiration Settings | Options are:- Reject request. For this example, you can select this option. > > - Reassign request > > - Do nothing | > | Notification Settings | Options are:- Assignment notification and email templates, such as `requestAssigned`. > > - Reassignment notification and email templates, such as `requestReassigned`. > > - Assignee reminders and email templates, such as `requestReminder`. > > * Sends every number of time periods, such as `3 day(s)`. > > - Escalation notifications and email templates, such as `requestEscalated`. > > * Send every number of day(s), such as `5 day(s)`. > > * Send to `Send escalation to` to `User` and select `User`. > > - Expiration notification and email templates, such as `requestExpired`. > > * Send a configured number of days before expiration. | * 6 Use the Script node to process any request rejections. > **Collapse: Click to display the Reject Request script** > > ```js > logger.info("Rejecting request"); > > var content = execution.getVariables(); > var requestId = content.get('id'); > > logger.info("Execution Content: " + content); > var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {}); > var decision = {'outcome': 'denied', 'status': 'complete', 'decision': 'rejected'}; > var queryParams = { '_action': 'update'}; > openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams); > ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Download the JSON file for this workflow [here](../_attachments/workflows/workflowUICreateNewUserWorkflowExample.json).Learn more about how to import or export workflows in [workflow editor canvas](workflow-configure.html#orch-ui-canvas). | ### Task 4: Submit the custom request You can enter a curl command to submit a Create New User request. ``` curl --location 'https:///iga/governance/requests/createNewUser' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "custom": { "userName": "acabby", "givenName": "Amy", "sn": "Cabby", "mail": "amy.cabby@example.com" } }' ``` > **Collapse: Example Response** > > ``` > { > "id": "d289d1dd-b376-4860-a3d9-db3dd29702b2", > "requester": { > "givenName": "Joe", > "id": "managed/teammember/ce6ef368-c050-4131-bc07-32aa4f58a785", > "mail": "joe.admin@example.com", > "sn": "Admin", > "userName": "jadmin" > }, > "requestType": "createNewUser", > "request": { > "custom": { > "userName": "acabby", > "givenName": "Amy", > "sn": "Cabby", > "mail": "amy.cabby@example.com" > }, > "_rev": 1, > "common": { > "isDraft": false, > "context": { > "type": "request" > } > } > }, > "decision": { > "status": "in-progress", > "decision": null, > "type": "request", > "outcome": null, > "startDate": "2024-09-09T15:53:49+00:00", > "completionDate": null, > "deadline": null, > "comments": [], > "actors": { > "active": [ > { > "givenName": "Frank", > "id": "managed/teammember/ce6ef368-c050-4131-bc07-32aa4f58a785", > "mail": "frank.york@exampe.com", > "sn": "York", > "userName": "fyork", > "permissions": { > "approve": false, > "comment": true, > "modify": false, > "forward": false, > "reject": false, > "cancel": false, > "fulfill": false, > "deny": false > } > } > ], > "inactive": [], > "actorTags": [ > "activeId=managed%2Fteammember%2Fce6ef368-c050-4131-bc07-32aa4f58a785&phase=", > "phase=&activeId=managed%2Fteammember%2Fce6ef368-c050-4131-bc07-32aa4f58a785" > ] > } > } > } > ``` ### Approver Task: Process the request 1. After the administrator submits the request, the approver (for example, "Frank York") receives a notification email. ![Notification email sent to the approver.](../_images/governance-end-user-approver-email.png) 2. The approver logs in to the Advanced Identity Cloud end-user UI and clicks Pending Approvals. ![Approver's hosted account page displaying requests](../_images/governance-end-user-approver-request.png) 3. The approver can carry out different tasks: click Approve, Reject, or ellipsis ([icon: more_horiz, set=material, size=inline]) to Forward, Add Comment, or View Details. ![Approver clicks the specific create user request](../_images/governance-end-user-approver-approvals.png) 4. The approver clicks View Details. ![The approver review the details of the request.](../_images/governance-end-user-approver-request-details.png)