Developing forms using REST APIs
You can include the "RestV2 API Infrastructure" (restapi) mixin model in your project and then develop forms for external systems using the REST APIs provided by NexJ Systems.
For information about implementing REST API v2, see Enabling and configuring REST API v2.
HTTP requests
You can use the following HTTP request methods in your code to consume, write to, or delete application server data for forms, and send your requests to the following resource endpoints:
| HTTP request method descriptions | Request type | Resource endpoints | Sample request body | Example |
|---|---|---|---|---|
| Read all flows | GET | <HTTP URL>/channel/rest:REST/flows | Not applicable | http://localhost:7080/nexj/channel/rest:REST/flows |
| Read a flow using its string ID | GET | <HTTP URL>/channel/rest:REST/flows/{stringID} | Not applicable | http://localhost:7080/nexj/channel/rest:REST/flows/10F33A2F285B154171BB8D95A7E1AC0E26 |
| Read all flow templates | GET | <HTTP URL>/channel/rest:REST/flowTemplates | Not applicable | http://localhost:7080/nexj/channel/rest:REST/flowTemplates |
Read a specific version of a flow template by its alternate key | GET | <HTTP URL>/channel/rest:REST/flowTemplates/{templateName.templateVersion} | Not applicable | http://localhost:7080/nexj/channel/rest:REST/flowTemplates/sampleFlow.2 For example, if there are two templates named "sampleFlow," versioned 1 and 2 respectively, the response will be version 2 of template "sampleFlow." |
| Read the latest version of a flow template by its alternate key | GET | <HTTP URL>/channel/rest:REST/flowTemplates/{templateName} | Not applicable | http://localhost:7080/nexj/channel/rest:REST/flowTemplates/sampleFlow For example, if there are two templates named "sampleFlow," versioned 1 and 2 respectively, the response will be version 2 of template "sampleFlow." |
| Create a flow associated with the latest version of a specific template | POST | <HTTP URL>/channel/rest:REST/flows | {
"template": "sampleFlow",
"isTransient": "false",
"status": "PROCESSED"
}
The | http://localhost:7080/nexj/channel/rest:REST/flows The sample request body creates a flow associated with the latest version of template "sampleFlow," when |
| Create a flow associated with a specific template | POST | <HTTP URL>/channel/rest:REST/flows | {
"template": "sampleFlow.2",
"isTransient": "false",
"status": "PROCESSED"
}
The | http://localhost:7080/nexj/channel/rest:REST/flows The sample request body creates a flow associated with version 2 of the template "sampleFlow," when |
| Create a specific version of a flow template | POST | <HTTP URL>/channel/rest:REST/flowTemplates The client-timezone key is required in the request header, for example: | {
"name": "sampleFlow",
"version": "2",
"dslType": "scm",
"bind": "Person"
}
The "name" key is a required key. | http://localhost:7080/nexj/channel/rest:REST/flowTemplates The sample request body creates version 2 of template "sampleFlow," when the |
| Create a new version of a flow template | POST | <HTTP URL>/channel/rest:REST/flowTemplates The client-timezone key is required in the request header, for example: | {
"name": "sampleFlow",
"dslType": "scm",
"bind": "Person"
}
The "name" key is a required key. | http://localhost:7080/nexj/channel/rest:REST/flowTemplates The sample request body creates version 3 of template "sampleFlow," when |
| Update a specific flow | PUT | <HTTP URL>/channel/rest:REST/flows/{stringID} The "$commit-hash" is required in the request body of PUT. It can be obtained from the response of a GET request to the same URL. The client-timezone key is required in the request header, for example: | {
"$commit-hash": 163004577,
"status": "PENDING"
}
| http://localhost:7080/nexj/channel/rest:REST/flows/10F33A2F285B154171BB8D95A7E1AC0E26 The sample request body updates the |
| Update a specific flow template | PUT | <HTTP URL>/channel/rest:REST/flowTemplates/{templateName} or <HTTP URL>/channel/rest:REST/flowTemplates/{templateName.templateVersion} The The client-timezone key is required in the request header, for example: | {
"$commit-hash": 1796111967,
"dslType": "NJS"
}
| http://localhost:7080/nexj/channel/rest:REST/flowTemplates/sampleFlow When the sample request body is sent to the above URL, the http://localhost:7080/nexj/channel/rest:REST/flowTemplates/sampleFlow.2 When the sample request body is sent to the the above URL, the |
| Delete a flow using its string ID | DELETE | <HTTP URL>/channel/rest:REST/flows/{stringID} | Not applicable | http://localhost:7080/nexj/channel/rest:REST/flows/10F33A2F285B154171BB8D95A7E1AC0E26 |
| Delete a specific version of a flow template by its alternate key | DELETE | <HTTP URL>/channel/rest:REST/flowTemplates/{templateName.templateVersion} | Not applicable | http://localhost:7080/nexj/channel/rest:REST/flowTemplates/sampleFlow.2 Version 2 of template "sampleFlow" will be deleted. |
| Delete the latest version of a flow template by its alternate key | DELETE | <HTTP URL>/channel/rest:REST/flowTemplates/{templateName} | Not applicable | http://localhost:7080/nexj/channel/rest:REST/flowTemplates/sampleFlow For example, if there are two templates named "sampleFlow," versioned 1 and 2 respectively, version 2 of template "sampleFlow" will be deleted. |
| Read selection options for flow "status" | GET | <HTTP URL>/channel/rest:SelectionOptions/flows/status | Not applicable | http://localhost:7080/nexj/channel/rest:SelectionOptions/flows/status |
| Read the schema model of flow | GET | <HTTP URL>/channel/rest:OpenAPI/en/schemas/flow.json | Not applicable | http://localhost:7080/nexj/channel/rest:OpenAPI/en/schemas/flow.json |
| Read the schema model of flow template | GET | <HTTP URL>/channel/rest:OpenAPI/en/schemas/flowTemplate.json | Not applicable | http://localhost:7080/nexj/channel/rest:OpenAPI/en/schemas/flowTemplate.json |
| Link to the full OpenAPI specification in JSON format. | Not applicable | <HTTP URL>/channel/rest:OpenAPI/en/openAPI.json | Not applicable | http://localhost:7080/nexj/channel/rest:OpenAPI/en/openAPI.json |
| Link to SwaggerUI | Not applicable | <HTTP URL>/rest:SwaggerUI.html | Not applicable | http://localhost:7080/nexj/rest:SwaggerUI.html The full list of endpoints, parameters, response codes, and model fields are provided in the SwaggerUI page. |
Due to current REST V2 limitations, the request body only supports string values. As a result, the following actions are not supported for POST and PUT:
- When creating or updating a flow using POST or PUT, specifying "globals" for initializing values in a flow.
- When creating or updating a flow template using POST or PUT, specifying a DSL definition.
For example, if a form is bound to a Know your Customer (KYC), you cannot pass in a contactId to initialize the For field through REST.
Responses
The following information shows examples for the responses that are returned to the client (browser) for requests:
GET the latest version of a flow template {<flowTemplateName>}: http://localhost:7080/nexj/channel/rest:REST/flowTemplates/{<flowTemplateName>}
POST the latest version of a flow template {<flowTemplateName>}: http://localhost:7080/nexj/channel/rest:REST/flowTemplates
The following example shows a request:
{
"name": {<flowTemplateName>},
"dslType": "scm",
"bind": "Person"
}
The following example shows a response:
PUT the latest version of a flow template {<flowTemplateName>}: http://localhost:7080/nexj/channel/rest:REST/flowTemplates/{<flowTemplateName>}
To use a PUT request, you must first use a GET request to obtain the $commit-hash. The following example shows a response for a GET to the URL to obtain the $commit-hash:
PUT to http://localhost:7080/nexj/channel/rest:REST/flowTemplates/{<flowTemplateName>}to update the "dslType"
After you have obtained the $commit-hash, you can request an update to the dslType:
{
"$commit-hash": 1460810791,
"dslType": "NJS"
}
The following example shows a response:
PUT with an invalid "$commit-hash"
If you pass in a wrong $commit-hash using any PUT request, you will obtain the following response:
{
"httpMessage": "Conflict",
"httpCode": 409,
"moreInformation": "Potential update conflict with bp:FlowTemplate {<flowTemplateName>}. Latest $commit-hash is 1568761430"
}
POST or PUT without the client-timezone header
If you use a POST or PUT request, and do not pass in a client-timezone key in the request header, you will obtain the following response:
{
"httpCode": 400,
"httpMessage": "Bad Request"
}
DELETE the latest version of a flow template "templateWithoutAssociatedFlows": http://localhost:7080/nexj/channel/rest:REST/flowTemplates/templateWithoutAssociatedFlows
{
"details": [
"Deleted bp:FlowTemplate templateWithoutAssociatedFlows"
],
"message": "Delete success"
}
DELETE the latest version of a flow template "templateWithAssociatedFlows": http://localhost:7080/nexj/channel/rest:REST/flowTemplates/templateWithAssociatedFlows
GET, PUT, or DELETE a non-existed flow template: http://localhost:7080/nexj/channel/rest:REST/flowTemplates/nonexistedTemplate
If you perform a GET, PUT, or DELETE request for a flow template that doesn't exist, you will receive the following response:
{
"httpMessage": "Not Found",
"httpCode": 404,
"moreInformation": "bp:FlowTemplate nonexistedTemplate does not exist"
}
Binding forms with an external schema model and object using REST APIs
NexJ supports binding a form with an external schema model and an external form related object obtained through a REST GET request.
Configuration
To integrate a Process Management form with a new external resource, the following configurations are required:
Project configuration
Create a new channel named
rest:{<externalResourceName>}and specify the URL. For example:Channel rest:exampleResource.channelExample rest:exampleResource.channel<HTTP delete="true" description="Inbound HTTP channel to send REST request" get="true" put="true" url="https://master.atmos.nexj.exampleResource/api/rest/"/>
Create a new meta file named
rest:{<externalResourceName>}:SchemaModel(for example,rest:exampleResource:SchemaModel). This file should apply thebp:rest:SCHEMA_MODELaspect and override the following events:getRelatedObjectPayloadevent for generating a request payload for getting an external related object used by a flowgetSchemaRequestPayloadevent for generating a request payload for getting the schema modelgetSyncRequestPayloadevent for generating a request payload for syncing an update to external objectsgetExternalEnumevent for getting the options of an external enumerationgetExternalObjectevent for generating a request payload for getting an external objectgetExternalObjectsevent for getting a list of external objects when a bind schema name is given, pagination and ordering should be implemented in it
- Create a new meta file named
rest:{<externalResourceName>}:ExternalObject. This file should setbp:rest:ExternalObjectas the base class, and specify a list of associated fields used in objects, as well as all the fields exposed for object type fields over API, as attributes of this meta class. For example, specify acaptionto represent a field caption exposed for object type fields, or specify anentityto represent the associated field entity exposed for object field entities.
Form configuration
- Specify the bind of the form in the following format:
REST.{<externalResourceName>}.{<schemaName>}
For example:REST.exampleResource.Person - Specify the options property for combo and radio controls if an external definition is used. For more information, see Using an external enumeration.
- Specify properties for an object or objects control if you bind the control with external objects. For more information, see Using external objects.
Mock schema model
The following example shows the definition for the sample REST schema model called personSchema.
personSchema has the following attributes:
| Attribute name | Title | Type | Options | Other properties |
|---|---|---|---|---|
| name | Last Name | string | Not applicable | maximum length: 256 characters |
| firstName | First Name | String | Not applicable | maximum length: 256 characters |
| gender | Gender | Enumeration | Default options: "FEMALE," "MALE," and "UNKNOWN" | bounded: true |
| maritalStatus | Marital Status | Enumeration | Default options: "COMMON_LAW" "DIVORCED" "MARRIED" "SINGLE" "WIDOWED" | Not applicable |
| birthCountry | Country | Enumeration | Default options: "CANADA," "UNITED_STATES_OF_AMERICA," and "OTHER" External mock options are shown in the Mock external enumeration section. | read only: true |
| residenceCountry | Country of Residence | Enumeration | Default options: "CANADA," "UNITED_STATES_OF_AMERICA," and "OTHER" External mock options are shown in the Mock external enumeration section. | Not applicable |
| primaryLanguage | Primary Language | Enumeration | Default options: "ARABIC" "MANDARIN" "GERMAN" "ENGLISH" "FRENCH" "PORTUGUESE" "RUSSIAN" "SPANISH" "CANTONESE" External mock options are shown in the Mock external enumeration section. | Not applicable |
| birthDate | Birth Date | string | Not applicable | format: date |
| isDoNotCall | Do Not Call | boolean | Not applicable | Not applicable |
| owner | Owner | object | Shown in the Mock external objects section. | Object attributes: ui_caption, $id |
| parties | Related Parties | array | Shown in the Mock external objects section. | Object attributes: Associated object party attributes: |
| identifications | Identifications | array | Shown in the Mock external objects section. | Object attributes: ui_caption, $id |
| telcoms | Communication | array | Not applicable | required attributes: template, typeName, address |
The required properties under each object indicate all the required attributes for it, and which values should not be null when the form is being submitted. Null values will generate an error message.
Using an external enumeration
To bind a combo or radio control with an external enumeration, specify (: options "REST.{<externalResourceName>}.{<schemaName>}.enum.<{enumerationName}>") in the definition. Combo or radio controls that bind with an external enumeration display their external options when you specify the options property and an external definition exists. Otherwise, they show the default options provided in the schema model definition. For example:
; Configure combo gender to use external enumeration named "gender" (bp:combo gender (: options "REST.mock.Contact.enum.gender")) ; Configure combo template to use external enumeration named "template" ; "template" is an associated field of "telcoms", so option property is configured to "REST.mock.Contact.enum.telcoms.template" (bp:combo template (: options "REST.mock.Contact.enum.telcoms.template")) ; Configure radio maritalStatus to use external enumeration named "maritalStatus" ; no external definition of "maritalStatus" is provided, thus this radio uses default options provided in mock schema model (bp:radio maritalStatus (: options "REST.mock.Contact.enum.maritalStatus")) ; radio birthCountry uses default options provided in mock schema model as option property is not configured (bp:radio birthCountry)
Mock external enumeration
The mock external enumeration in the following example is used for combo and radio controls.
For example, if you bind a combo control with a gender enumeration, it displays the following mock external options: "Male," "Female," and "Unknown."
Using external objects
When you bind Process Management forms with the external REST schema model objects, some properties are optional. This is different from when you bind forms with the NexJ model objects where these same properties are required.
Object(s) properties:
valueCaption
It is a required property.assoc
It is a required property when a multipicker control requiresassocto be specified.valueType
It is a non-required property. It is calculated to be in the format of"REST.<{externalProjectName}>.<{schemaName}>.object.<{bindName}>". For example:REST.exampleResource.Person.object.entitiesassocType
It is a non-required property. It is calculated to be in the format of"REST.<{externalProjectName}>.<{schemaName}>.object.<{bindName}>.<{assocName}>". For example:REST.exampleResource.Person.object.entities.entityfilterPath
It is an optional property. Custom filtering can be implemented ingetExternalObjects, as mentioned in Project configuration.order
It is an optional property. Custom ordering can be implemented ingetExternalObjects, as mentioned in Project configuration.initialize
It is an optional property for the create instance case. Its value format is one of the following:object: (: initialize (message (: id <{string_id}>) (: type "REST.<{externalProjectName}>.<{schemaName}>")))objects: (: initialize (collection(message (: id <{string_id}>) (: type "REST.<{externalProjectName}>.<{schemaName}>"))))
The following example shows how to use object, objects with external objects, the valueType, and assocType values.
Mock external objects
Mock external objects are used as items that display in M1 and MM pickers. For example, if you are using a M1 picker that has an objectType that is calculated to REST.mock.Contact.object.owner, when a user clicks the Select 
button on the picker control, the options shown in the following code example for owner are displayed in the picker. A user can then select any of the options inside the picker in order to specify the value for owner.
Mock related object
The following example shows the properties of the sample external contact called "Tim Lamont":
Sample form using the mock schema model
This section provides examples that show how to edit an existing instance and create a new instance.
Example: Editing an existing instance
The following example shows how to bind a form using personSchema and "Tim Lamont":
The value of the objectId property should be the ID of the external object, and the value of the idFormat property should be the key of the ID for the external object. By default, idFormat is set to '$id.
NexJ provides a sample mock model, which has the same definition as personSchema and sample object "Tim Lamont." When you bind the above form to REST.mock.Contact, the mock model is used.
A form template called "testschemabind," which is similar to the form shown in the "Binding a form using personSchema and Tim Lamont" example, is also provided in Process Management.
Example: Creating a new instance
When you are creating the flow to use an integrated form to create a new instance, you do not need to pass in an objectId. This is similar to using the forms bind with NexJ model objects.
(define flow (bp:Flow'createFlow (bp:FlowTemplate'createTemplate "newInstance" definition) (: idFormat '$id))) (commit)
The mock model does not support creating a new contact.
Form submission
After a user make changes in a form and clicks Submit, Process Management automatically generates the required REST PUT, POST, and DELETE requests, and sends these requests to external services to save the changes to the external objects.
Conflicts
Conflicts are shown when an external object has been updated but the Process Management form still contains its old values. When creating a form, a proper idFormat needs to be passed in, as shown in the sample code above. Otherwise, improper conflicts are shown for collection items, which is caused by a failure to read items based on their ID.
Related link
Enabling and configuring REST API v2