Start Form JSON Process API

The Start Form Json Process API allows to start a Form workflow process. This API uses POST method to start a workflow process. The initial form data should be sent in JSON format. It should be a valid JSON form as no data validation is performed and no field rules are executed when saving the form data.

Overview of API

Below is an overview of Start Form Json Process API :

  1. It supports Name Template feature. The Name Template should be configured with Form Name control. Property of Form Name control Run At should be set to End. While calling the Digital Access API, the Form field mapped to the Field Name property of the Form Name control should be empty.

  2. The Evolve user specified as form submitter must have Originator role on the solution for which new form process needs to be started.

  3. Optionally process participant or SwimLane user can also be specified in API request.

  4. A Form Workflow started from API will be tagged as API document and if resubmitted manually, the canceled process document will still be considered as API document. This information will be considered for license billing.

  5. Copying a form document creates a new document in system. The document copied from an API document and launched/submitted manually from Web UI, will be considered as non-API document (i.e. manual submitted document).

Request and Response body

For starting a form Process through API with FormFields in JSON format, the structure of Request and response will be like:

Request Data Contract:

Name Type Restriction Description
Formfields string -

  • This is the Form data of the new Form Process.

  • This should be in JSON format, where key name should be form field name (case sensitive) and value should be the data. This is further clarified in the the example given below.

  • Form Fields not specified in JSON format will be set with default value as set in Form Data schema in Form Solution.
ParticipantsInfoArray Jarray of { “SwimlaneName” : ”abc”, “UserName”: ”xyz” } -

This should be swimlane name, which should be resolved with given users.

  • “SwimlaneName” : Name of swimlane.

  • “UserName”: List of usernames separated by comma.

If either this parameter is left blank or specific swimlanes details are not provided, in such cases application will resolve these swimlanes as per behavior defined in workflow.

For Person Type swimlane in the form workflow, the swimlane user value cannot be overridden while launching the form via API.
Comments string - Comments for Start Node.
AppName string Required App name of the "Form Solution".
LibName string Required Library name of the "Form Solution".
TemplateName string Required Name for the "Form Solution".
UserName string Required UserName of the user who will be set as process originator. The user must have originator role on the solution for which new form process needs to be started.

FormFields Property values examples:

Example1: Composer Form has two fields “Product_Name” and “Product_Description”, so the value of property “FormFields” should be

Formfields

{"my:myFields": {"my:Product_Name": "","my:Product_Description": ""}}

Example2: Composer Form has three fields (Form header fields) and a Table with three fields (three columns). Limited field values can also be passed to API i.e. value of two header fields, and table values for two table fields can be passed.

Formfields

{
  "my:myFields":{
    "my:Product_Name":"test3",
    "my:Product_Description":"test2",
    "my:Repeating_Table_9":{
       "my:Repeating_Content":[
         {"my:TableColumn1":"val1","my:TableColumn2":"100"},
         {"my:TableColumn1":"val2","my:TableColumn2":"200"}
]}}}

Response Data Contract

Name Type Restriction Description
processId Guid - Return ID of process.
FormItemId Guid -

Return ID of Form Document.

Request and Response sample

Following sample illustrates the use of API:

Route: http://Winshuttle.EvolveUrl/svr/api/v1/Processextn/StartFormJsonProcess

Request Payload 

{
  "AppName":"My APP",
  "LibName": "Form Process Ext",
  "TemplateName": "API Product Example",
  "UserName": "mydomain\\user1",
  "Comments": "Process from API2",
  "Formfields": {
    "my:myFields": {
      "my:Product_Name": "Evolve",
      "my:Product_Description": "Evolve Product Description"
    }
  },
  "ParticipantsInfoArray": [
    {
      "SwimLaneName": "PersonSwimlane",
      "UsersName": "mydomain\\user1"
    },
    {
      "SwimLaneName": "TeamSwimlane",
      "UsersName": "mydomain\\user1,mydomain\\user2"
    }
  ]
}

 

Response Payload

{
    "ProcessId": "ea03a42e-7eca-4b5d-af8f-d8e778d75e84",
    "FormItemId": "fc1f36dd-3302-4217-b052-f0d6246aa0e3"
}