Examples of forms
This section presents form examples of integration with workflow nodes.
This section covers the following form examples:
Example: Create a form for a custom request type
In this example, an administrator wants to complete the following tasks:
-
Create a custom request type using the API.
-
Create a simple form for the new custom request type.
-
Create a workflow to handle the custom request type and the form.
Assumptions
-
Each application has an application owner. You populate this value for each target application.
-
You have designated an end user who can approve the request.
Task 1: Create a custom request type
-
Create a custom request type called
createUser
using the API that lets an administrator easily add a new user to the system.The 'createUser' 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.
Currently, the only way to create a custom request type is through the API. The UI will support this functionality in a future release.
Enter the following command using cURL to create your custom request type:
Details
curl --location 'http://<hostname>/iga/governance/requestTypes' \ --header 'Authorization: Bearer token' \ --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
Using the UI
-
In the Advanced Identity Cloud admin UI, click Governance > Forms.
-
On the New Form modal, click Custom request form, and then click Next.
-
On 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.
One form can be assigned to multiple request types, but a request type can only be assigned to one form. Once you create your form, you can go back and make edits to any of the above form settings by clicking the ellipsis() in the top right, and then click Settings.
-
Use the Forms editor to create a form for your custom request type. For example, you will drag and drop four text fields onto the canvas for the fields:
User Name
,E-mail address
,First Name
, andLast Name
.-
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:User name text field properties
Field Description [.label]#Key
Enter the key for the text string. You can retrieve this key from the cURL step under the
schemas
entry. For example, entercustom.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.
Provide Default Value
Click Provide Default Value to assign a default value for this text field. In this example, skip this step.
Under Layout: Columns
Enter the number of columns for this text field. Values can be 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 can be from 1 to 12. 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.
-
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:E-mail address text field properties
Field Description [.label]#Key
Enter the key for the text string. You can retrieve this key from the cURL step under the
schemas
entry. For example, entercustom.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.
Provide Default Value
Click Provide Default Value to assign a default value for this text field. In this example, skip this step.
Under Layout: Columns
Enter the number of columns for this text field. Values can be 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 can be from 1 to 12. 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.
-
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:First name text field properties
Field Description [.label]#Key
Enter the key for the text string. You can retrieve this key from the cURL step under the
schemas
entry. For example, entercustom.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.
Provide Default Value
Click Provide Default Value to assign a default value for this text field. In this example, skip this step.
Under Layout: Columns
Enter the number of columns for this text field. Values can be 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 can be from 1 to 12. 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.
-
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:Last name text field properties
Field Description [.label]#Key
Enter the key for the text string. You can retrieve this key from the cURL step under the
schemas
entry. For example, entercustom.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.
Provide Default Value
Click Provide Default Value to assign a default value for this text field. In this example, skip this step.
Under Layout: Columns
Enter the number of columns for this text field. Values can be 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 can be from 1 to 12. 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.
-
-
Click Save.
Using the API
-
Enter the following cURL command to create your form for the custom request type:
Details
curl --location 'http://<hostname>/iga/governance/requestForms' \ --header 'Authorization: Bearer token' \ --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 } } ] } }'
Task 3: Create a workflow to use the custom request type and form
Create a new workflow called createNewUser
to use the custom request type and form.
Click to view a cURL command that publishes the Create New User workflow
curl --location 'http://openam-gov-dev-4.forgeblocks.com/auto/orchestration/definition?_action=publish' \ --header 'Authorization: Bearer token' \ --header 'Content-Type: application/json' \ --data-raw '{ "id": "createNewUser", "name": "createNewUser", "displayName": "Create New User", "description": "Create New User", "type": "provisioning", "_rev": 0, "steps": [ { "name": "approvalTask-74cf85c35437", "displayName": "Approval Task", "type": "approvalTask", "approvalTask": { "nextStep": [ { "condition": null, "outcome": "EXPIRATION", "step": null }, { "condition": null, "outcome": "APPROVE", "step": "scriptTask-0359a9d77ee2" }, { "condition": null, "outcome": "REJECT", "step": "scriptTask-aec6c36b3a45" } ], "approvalMode": "any", "actors": [ { "id": "managed/user/c51d9ee1-43b3-49d1-8742-cbb33842a5cc", "permissions": { "approve": true, "reject": true, "reassign": true, "modify": true, "comment": true } } ], "events": { "assignment": { "notification": "requestAssigned" }, "reassign": { "notification": "requestReassigned" }, "reminder": { "notification": "requestReminder", "frequency": 3, "date": { "isExpression": true, "value": "(new Date(new Date().getTime()(3*1*24*60*60*1000))).toISOString()" } }, "escalation": { "notification": "requestEscalated", "date": { "isExpression": true, "value": "(new Date(new Date().getTime()(5*1*24*60*60*1000))).toISOString()" }, "actors": [ { "id": "managed/user/517c1964-a205-4e1f-b8d8-590f29795c4d" } ] }, "expiration": { "action": "reject", "notification": "requestExpired", "actors": [ { "id": "managed/user/517c1964-a205-4e1f-b8d8-590f29795c4d" } ], "date": { "isExpression": true, "value": "(new Date(new Date().getTime()+(1*24*60*60*1000))).toISOString()" }, "frequency": 1 } } }, "approvalMode": "any" }, { "name": "scriptTask-0359a9d77ee2", "displayName": "Create User", "type": "scriptTask", "scriptTask": { "nextStep": [ { "condition": "true", "outcome": "done", "step": null } ], "language": "javascript", "script": "logger.info(\"Creating User\");\n\nvar content = execution.getVariables();\nvar requestId = content.get('\''id'\'');\nvar failureReason = null;\n\ntry {\n var requestObj = openidm.action('\''iga/governance/requests/'\'' + requestId, '\''GET'\'', {}, {});\n logger.info(\"requestObj: \" + requestObj);\n}\ncatch (e) {\n failureReason = \"Provisioning failed: Error reading request with id \" + requestId;\n}\n\nif(!failureReason) {\n try {\n var request = requestObj.request;\n var payload = {\n \"userName\": request.custom.userName,\n \"givenName\": request.custom.givenName,\n \"sn\": request.custom.sn,\n \"mail\": request.custom.mail,\n \"password\": '\''DemoP@ssword1'\''\n };\n\n / Create new user /\n var result = openidm.create('\''managed/alpha_user'\'', null, payload, queryParams);\n\n / Send new user email /\n var body = { \n subject: \"Welcome \" + payload.givenName + \" \" + payload.sn + \"!\",\n to: payload.mail,\n 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#/\",\n object: {}\n };\n openidm.action(\"external/email\", \"send\", body);\n }\n catch (e) {\n failureReason = \"Creating user failed: Error during creation of user \" + request.custom.userName + \". Error message: \" + e.message;\n }\n \n var decision = {'\''status'\'': '\''complete'\'', '\''decision'\'': '\''approved'\''};\n if (failureReason) {\n decision.outcome = '\''not provisioned'\'';\n decision.comment = failureReason;\n decision.failure = true;\n }\n else {\n decision.outcome = '\''provisioned'\'';\n }\n\n var queryParams = { '\''_action'\'': '\''update'\''};\n openidm.action('\''iga/governance/requests/'\'' + requestId, '\''POST'\'', decision, queryParams);\n logger.info(\"Request \" + requestId + \" completed.\");\n}" } }, { "name": "scriptTask-aec6c36b3a45", "displayName": "Reject Request", "type": "scriptTask", "scriptTask": { "nextStep": [ { "condition": "true", "outcome": "done", "step": null } ], "language": "javascript", "script": "logger.info(\"Rejecting request\");\n\nvar content = execution.getVariables();\nvar requestId = content.get('\''id'\'');\n\nlogger.info(\"Execution Content: \" + content);\nvar requestIndex = openidm.action('\''iga/governance/requests/'\'' + requestId, '\''GET'\'', {}, {});\nvar decision = {'\''outcome'\'': '\''denied'\'', '\''status'\'': '\''complete'\'', '\''decision'\'': '\''rejected'\''};\nvar queryParams = { '\''_action'\'': '\''update'\''};\nopenidm.action('\''iga/governance/requests/'\'' + requestId, '\''POST'\'', decision, queryParams);" } }, { "name": "scriptTask-d76490953517", "displayName": "Request Context Check", "type": "scriptTask", "scriptTask": { "nextStep": [ { "condition": "true", "outcome": "done", "step": "exclusiveGateway-8cd9decab2e4" } ], "language": "javascript", "script": "var content = execution.getVariables();\nvar requestId = content.get('\''id'\'');\nvar context = null;\nvar skipApproval = false;\ntry {\n var requestObj = openidm.action('\''iga/governance/requests/'\'' + requestId, '\''GET'\'', {}, {});\n if (requestObj.request.common.context) {\n context = requestObj.request.common.context.type;\n if (context == '\''admin'\'') {\n skipApproval = true;\n }\n }\n}\ncatch (e) {\n logger.info(\"Request Context Check failed \"+e.message);\n}\n\nlogger.info(\"Context: \" + context);\nexecution.setVariable(\"context\", context);\nexecution.setVariable(\"skipApproval\", skipApproval);" } }, { "name": "exclusiveGateway-8cd9decab2e4", "displayName": "Context Gateway", "type": "scriptTask", "scriptTask": { "nextStep": [ { "condition": "skipApproval == true", "outcome": "AutoApproval", "step": "scriptTask-8506123e6208" }, { "condition": "skipApproval == false", "outcome": "Approval", "step": "approvalTask-74cf85c35437" } ], "language": "javascript", "script": "logger.info(\"This is exclusive gateway\");" } }, { "name": "scriptTask-8506123e6208", "displayName": "Auto Approval", "type": "scriptTask", "scriptTask": { "nextStep": [ { "condition": "true", "outcome": "done", "step": "scriptTask-0359a9d77ee2" } ], "language": "javascript", "script": "var content = execution.getVariables();\nvar requestId = content.get('\''id'\'');\nvar context = content.get('\''context'\'');\nvar queryParams = {\n \"_action\": \"update\"\n}\ntry {\n var decision = {\n \"decision\": \"approved\",\n \"comment\": \"Request auto-approved due to request context: \" + context\n }\n openidm.action('\''iga/governance/requests/'\'' + requestId, '\''POST'\'', decision, queryParams);\n}\ncatch (e) {\n var failureReason = \"Failure updating decision on request. Error message: \" + e.message;\n var update = {'\''comment'\'': failureReason, '\''failure'\'': true};\n openidm.action('\''iga/governance/requests/'\'' + requestId, '\''POST'\'', update, queryParams);\n\n}" } } ], "staticNodes": { "startNode": { "id": "startNode", "x": 70, "y": 140, "connections": { "start": "scriptTask-d76490953517" } }, "endNode": { "id": "endNode", "x": 1172, "y": 175, "connections": null }, "uiConfig": { "approvalTask-74cf85c35437": { "actors": [ { "type": "user", "id": { "isExpression": false, "value": "managed/user/c51d9ee1-43b3-49d1-8742-cbb33842a5cc" } } ], "events": { "escalationType": "script", "escalationDate": 5, "escalationTimeSpan": "day(s)", "reminderDate": 3, "reminderTimeSpan": "day(s)", "expirationDate": 1 }, "x": 668, "y": 142 }, "scriptTask-0359a9d77ee2": { "x": 892, "y": 59.015625 }, "scriptTask-aec6c36b3a45": { "x": 891, "y": 228.015625 }, "scriptTask-d76490953517": { "x": 161, "y": 142.015625 }, "exclusiveGateway-8cd9decab2e4": { "x": 419, "y": 122.015625 }, "scriptTask-8506123e6208": { "x": 667, "y": 57.015625 } } } }'