Start Form Process API

The Start Form 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 XML format. It should be a valid Form XML because data validation or rule execution is not performed while saving the Form data.

Overview of API

Below is an overview of Start 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 the structure of Request and response will be like:

Request Data Contract:

Name Type Restriction Description
AppName string Required App name of the “Form Solution”.
Comments string - Comments for Start Node.
FormXML string - This is the Form data of the new form process. This should be a valid Form XML for the Form solution.
LibName string Required Library name of the "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.
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.

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/StartFormProcess

Request Payload 

{
  "AppName":"My API",
  "LibName": "Form Process Ext",
  "TemplateName": "API Product Example",
  "UserName": "mydomain\\user1",
  "Comments": "Process from API2",
  "FormXml": "<my:myFields xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xhtml=\"http://www.w3.org/1999/xhtml\" xmlns:d=\"http://schemas.microsoft.com/office/infopath/2003/ado/dataFields\" 
xmlns:dfs=\"http://schemas.microsoft.com/office/infopath/2003/dataFormSolution\" xmlns:my=\"http://schemas.microsoft.com/office/infopath/2003/myXSD\" xmlns:xd=\"http://schemas.microsoft.com/office/infopath/2003\"
 xmlns:msxsl=\"urn:schemas-microsoft-com:xslt\">
<my:Product_Name>Evolve</my:Product_Name><my:Product_Description>Evolve product desc</my:Product_Description></my:myFields>",
  "ParticipantsInfoArray": [
    {
      "SwimLaneName": "PersonSwimlane",
      "UsersName": "mydomain\\user1"
    },
    {
      "SwimLaneName": "TeamSwimlane",
      "UsersName": "mydomain\\user1,mydomain\\user2"
    }
  ]
}

Response Payload

{
    "ProcessId": "93ae1e24-366e-4e54-af5c-dbf34ec15797",
    "FormItemId": "0e6c9998-3e3d-4e89-9fd4-e8086312cb32"
}