Start Excel Process API

The Start Excel Process API allows to start an Excel Workflow process. The submitted Excel file gets submitted to respective solution library and a new process gets started on this new document. This API uses POST method to start a workflow process.

Overview of API

Below is an overview of Start Excel Process API :

  1. It supports Excel Workflow Name Template feature. ExcelWorkflowObj.DataFile.Title property will be ignored if the target Excel process is configured with Name Template of data file. Also, the next name from Name Template will be used to set the name of the document.

  2. API supports preference "Version Control: Version Control for Data Templates", this is app level preference and supported when the data file is submitted to API route/Template.

    Also route/File can be used to submit an Excel file for the one which are not created from Data Template file. File submitted to this route will be consider as Latest Template file. So the preference “Version Control for Data Templates” wont have any significance for it

  3. The Evolve User specified as file submitter must have Originator role on the solution.

  4. The Evolve User specified as file submitter must have a valid User Name license (i.e. Runner or Standard etc.).

  5. Process participant or Swimlane user cannot be specified in API request. This is same as submitting a Excel file from Studio Microsoft Excel add-in.

  6. Supports solution fields sync feature.

  7. Supports Query Where clause (i.e. RTV Format). Autorun for Query script having input file via Excel Process API would work fine when the RTV info is provided.

  8. Excel Data File created from "Solution Template Excel File" should be submitted to route : {API Route}/Template.

  9. Excel Data file not created from "Solution Template Excel File" should be submitted to route : {API Route}/File.

    • This won't be supporting Version control for data template.

    • Submitted Excel file columns/data structure should be as per mapping defined for given Excel Solution scripts. A wrong file will cause workflow execution errors or data posting errors.

  10. If either Template or File is not specified then system processes the request as routed with "{API Route}/File".

  11. Resubmitting data file with same name through API is not allowed.

  12. An Excel 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.

Request and Response body

For starting an Excel Process with given Excel Template through API the structure of Request and response will be like:

Request Data Contract

Name Type Restriction Description
ExcelWorkflowObj Jobject Required Data File and supporting documents to be sent as JSON object. The JSON object schema details is given at end of this table. Data File and supporting document should be in base64String encoded.
UserName string Required This is the Evolve User Name. The user must have Originator permissions on the Solution, for which the template gets submitted.
AppName string Required App Name where this Excel process should be initiated. Excel Template solution or library must exists in this App only.
LibName string Required only for non solution template excel file. i.e. {API Route}/File Library name of the Excel Solution.
TemplateName string Required only for non solution template excel file. i.e. {API Route}/File Name for the "Excel Solution".

ExcelWorkflowObj parameter JSON schema details:

"ExcelWorkflowObj":{
"DataFile":[{
  "Title": "ExcelDataFileName1.xlsx",
  "RTVInfo": "",
  "Description": "",
  "DataFileBlob": "<<Base64EncodedString>>"
}],
"SupportingFiles":[{
  "Title": "SupportingFileName1.xlsx",
  "Description": "",
  "FileBlob": "<<supporting file blob>>"},
{
  "Title": "SupportingFileName2.txt",
  "Description": "",
  "FileBlob": "<<Base64EncodedString>>"
}]
}

ExcelWorkflowObj.DataFile: Although this is array type, but only first array element is supported and will be used by the API.

ExcelWorkflowObj.SupportingFiles : Multiple supporting files can be submitted.

Response Data Contract:

Name Type Restriction Description
DocumentItemId Guid - Return ID of Excel Document

Request and Response sample

Following sample illustrates the use of API:

Request Payload 

{
  "LibName":"Excel Workbooks",
  "UserName":"wsdt\\centraluser",
  "ExcelWorkflowObj":
  {
    "DataFile":
    [
      {
      "Description":"",
      "DataFileBlob":"UEsDBBQABgAIAAAAIQComKncbgEAAJUFAAATAAgCW0NvbnRlbnRfVHlw...",
      "RTVInfo":"",
      "Title":"publish10474.xlsx"
      }
    ]
  },
  "TemplateName":"MM02_EPIM",
  "AppName":"Arpit App"
}

Response Payload

{
    "DocumentItemId": "ea03a42e-7eca-4b5d-af8f-d8e778d75e84"
}