2023:API Services (Service): Difference between revisions

From Grooper Wiki
← Older editNewer edit →
Line 482: Line 482:
"FieldValues": [
"FieldValues": [
   {
   {
     "Key": "Social Sec Num",
     "Key": "Social_Sec_Num",
     "Value": "000-00-0000"
     "Value": "000-00-0000"
   }
   }

Revision as of 11:23, 18 April 2024

This article is about an older version of Grooper.

Information may be out of date and UI elements may have changed.

202520242023.12023

You can perform Batch processing via REST API web calls by installing API Services.

About

The Grooper REST API (Application Programming Interface) allows for seamless integration between line of business solutions or custom-built software and your existing Grooper repositories and processes. A set of REST API methods allows users to push documents through Grooper Batch Processes and retrieve the results.

For example, using the Grooper REST API you can:

  • Get information about a single Batch or all Batches
  • Create a new Batch
  • Delete a Batch
  • Start or resume a Batch Process
  • Get metadata for a specified Batch Folder.
  • And more!

The first step in using the Grooper REST API is setting up an API endpoint for your 3rd party application to interact with a Grooper Repository. To do this, you will need to install a Grooper service in Grooper Config called API Services.

⚠

You must register an API key for the API endpoint to function. The API key is passed in the HTML header for Grooper's API calls as a key-value pair.

  • key name: apikey
  • value format (GUID): 00000000-0000-0000-0000-000000000000

Instructions on how to obtain an API key are found in the How to install the Grooper API Services tutorial.

How To: Install the Grooper API Services

⚠

The Grooper Service User must have the "Logon as Service" permission."

  1. In Grooper config click the "Edit Services" button to open the "Service Manager" window.


  2. From the Service Manager window click the "Install" button.
  3. Select the desired repository from the "Repository" dropdown.
  4. Choose API Services.
  5. Click the "OK" button to confirm and open the "API Services" window.


  2. From the "API Services" window add an API key for the API Keys property.
  3. Copy the API endpoint URL from the URL property.
  4. Ensure the Windows service user credentials are correct on the User Name and Password properties.
  5. When finished configuring click the "Execute" button to confirm changes and close the "API Services" window.


  2. In the "Service Manager" window, with the newly created "Grooper API Services" service installed and selected, click the "Start" button.
    • FYI - If everything was configured properly, the "Status" of the service will change from "Stopped" to "Running".

How Tow: Enable a Grooper API Test Endpoint

When using the Grooper REST API, you may find it helpful to test out certain API calls before you implement them. By turning the Enable Test Endpoint property on, you can expose a Grooper REST API testing interface which you can access by entering the API URL in a browser.

  1. When editing an "API Services" service, in the "API Services" window, set the Enable Test Endpoint property to True.
  2. Copy the API endpoint URL from the URL property.
  3. When finished configuring click the "Execute" button to confirm changes and close the "API Services" window.



  2. Paste the copied URL into a browser of your choice.



From here, you can view and test the various REST API methods available to process documents in Grooper.

Testing Grooper API endpoints

Be aware this section is a work-in-progress. For more information about each API endpoint, set up a test endpoint and try it out for yourself!

Here, you will find more information about testing the Grooper API endpoints.

  • Note, parameters you can pass with the request are in curly brackets.
  • Example: You would replace {BatchID} with the GUID of a Batch.

⚠

PLEASE NOTE: Browsers will cache certain values entered in the API tester. This can cause confusion when testing endpoints with optional data (particularly the CreateBatch and CreateFolder endpoints). There are scenarios where cached values may be used unexpectedly.

The Grooper API Tester is meant for quick and simple tests. We recommend using a more robust API tester (such as Postman) before implementation.

DeleteBatch: Delete a Batch

DELETE {baseUrl}/api/v1/BatchProcessing/Batches/{BatchID}


This request will delete a Batch in Grooper. Enter a Batch's GUID to delete it.

  • If successfully deleted, the response will be true

GetBatchInfo: Get info for a specific Batch

GET {baseUrl}/api/v1/BatchProcessing/Batches/{BatchID}


This request will give you information about a Batch in Grooper (its "Id", "Name", "Status" and more property values). Enter the Batch's GUID to return information about it.

  • You will receive a JSON response containing information about the Batch.

See below for an example response: 

{
  "Id": "be0336a2-5e9a-4f60-83d0-15ea4b092cd9",
  "Name": "Invoices",
  "NodeIndex": 2,
  "NumChildren": 2,
  "ParentId": "46225e5b-c2a5-4d30-9bf8-68646e5e11fc",
  "TypeName": "Grooper.Core.Batch",
  "Created": "/Date(1664458774624-0500)/",
  "CreatedBy": "BIS\\dgreenwood",
  "Priority": 3,
  "RootFolderId": "7b80c102-2a22-4525-b05a-a1389849425a",
  "Status": 4,
  "StepNo": -1
}

GetBatchInfos: Get info for all Batches (Production branch only)

GET {baseUrl}/api/v1/BatchProcessing/Batches/All/All?Level={Level}


The Batches/All call returns information about all production Batches in a Grooper Repository at a specified level.

Entering a {Level} of 0 will return information about all production Batches at all folder levels.

  • This is the most common request but can be computationally inefficient as Grooper must iterated through various nodes to determine if Batches are present at multiple levels in the Production branch.

Entering a {Level} other than 0 will return information about production Batches only at the specified level of the Production branch.

  • This can be more efficient if you expect all your Batches to be at the same level.
  • In the example below, we set {Level} to 2, returning information about the single Batch at the second level of the Production branch.

GetContentStream: Get data from a file in the Grooper file store

GET {baseUrl}/api/v1/BatchProcessing/Files/{ItemId}/{FileName}


This request returns information about files in the Grooper file store. You will need to enter two things:

  • The item's GUID (often a Batch Folder's GUID)
  • The file's name (often a file associated with or attached to that Batch Folder)


Depending on the file type, the API will return:

  • For most file types, the API will return the file's MIME type and file size.
  • For JSON files, the API will return the full JSON content. This could be used to return any number of things, including the full JSON for the "Grooper.DocumentData.json" file generated for a Batch Folder after it was extracted.


In this example, {ItemId} was set to the GUID of a Batch Folder and {FileName} was set to the name of an attached PDF.

  • The MIME type and file size for that file was returned.


See below for an example response for a pdf file: 

Type: application/pdf, Size: 75922


See below for an example response of a "Grooper.DocumentData.json" file: 

{
  "Ch": [
    {
      "__type": "FieldInstance:#Grooper.Core",
      "Val": "30cbbb98-bada-407d-aaca-573748e31350",
      "IxId": "88e97d14-c60a-4133-8efc-30d81bd9afcb",
      "Name": "GUID",
      "FC": 1
    },
    {
      "__type": "SectionInstance:#Grooper.Core",
      "Ch": [
        {
          "__type": "FieldInstance:#Grooper.Core",
          "Val": "#PBJ001",
          "CI": [
            {
              "Val": "INVOICE NUMBER",
              "Name": "Invoice Number",
              "Idx": 91,
              "Len": 14,
              "Loc": {
                "X1": 0.75,
                "Y1": 1.8458,
                "X2": 2.0267,
                "Y2": 1.9458
              },
              "FC": 1
            }
          ],
          "IxId": "f165f384-7fda-4dd6-ade5-2ff9bb65866b",
          "Idx": 120,
          "Len": 7,
          "Name": "Invoice Number",
          "Loc": {
            "X1": 2.7275,
            "Y1": 2.1858,
            "X2": 3.3225,
            "Y2": 2.2858
          },
          "FC": 1
        },
        {
          "__type": "FieldInstance:#Grooper.Core",
          "Val": "10/19/2009",
          "CI": [
            {
              "Val": "INVOICE DATE",
              "Name": "Invoice Date",
              "Idx": 106,
              "Len": 12,
              "Loc": {
                "X1": 3.5,
                "Y1": 1.8458,
                "X2": 4.5125,
                "Y2": 1.9458
              },
              "FC": 1
            }
          ],
          "IxId": "c2692a97-2a71-442a-91d3-d753978bf8b1",
          "Idx": 128,
          "Len": 10,
          "Name": "Invoice Date",
          "Loc": {
            "X1": 5.2808,
            "Y1": 2.1725,
            "X2": 6.0775,
            "Y2": 2.3008
          },
          "FC": 1
        },
        {
          "__type": "FieldInstance:#Grooper.Core",
          "Val": "688.98",
          "CI": [
            {
              "Val": "TOTAL $",
              "Name": "Invoice Total",
              "Idx": 441,
              "Len": 7,
              "Loc": {
                "X1": 5.9125,
                "Y1": 7.0633,
                "X2": 6.4909,
                "Y2": 7.1783
              },
              "FC": 1
            }
          ],
          "IxId": "b9e8adb4-4a16-45e1-b10b-6048bd81e39b",
          "Idx": 488,
          "Len": 6,
          "Name": "Invoice Total",
          "Loc": {
            "X1": 7.3933,
            "Y1": 7.47,
            "X2": 7.8517,
            "Y2": 7.5692
          },
          "FC": 1
        }
      ],
      "IxId": "d13da629-8f65-4a49-ac22-13d9a629e2ba",
      "Spans": [
        {
          "Length": 752
        }
      ],
      "Name": "Header Details",
      "Loc": {
        "X1": 0.51,
        "Y1": 0.5483,
        "X2": 8.0008,
        "Y2": 10.3175
      }
    }
  ],
  "IxId": "68dc0073-3ee9-4b3f-af9e-963380a5763e",
  "Name": "Data Model",
  "Loc": {
    "X1": 0.51,
    "Y1": 0.5483,
    "X2": 8.0008,
    "Y2": 10.3175
  },
  "FC": 0.5
}

GetContentTypes: Get info for all Content Types

GET {baseUrl}/api/v1/BatchProcessing/ContentTypes


This request returns information about all Content Types (Content Models, Content Categories and Document Types) in your repository.

  • There is no configuration necessary.

See below for an example response. This response is from a Grooper Repository that only has a single Content Model (named "HR Model - Small") with three Document Types (named "Benefits Questionnaire" "Data Change" and "Data Info"): 

[
  {
    "Id": "bc22effb-0db9-4d1e-9665-2209206cd13c",
    "Name": "HR Model - Small",
    "NodeIndex": 0,
    "NumChildren": 5,
    "ParentId": "6cc455ff-a386-4e7a-a924-8ef367c637fa",
    "TypeName": "Grooper.Core.ContentModel",
    "Children": [
      {
        "Id": "97b3b424-72ad-47ed-8d94-73a42df8e06a",
        "Name": "Benefits Questionnaire",
        "NodeIndex": 2,
        "NumChildren": 1,
        "ParentId": "bc22effb-0db9-4d1e-9665-2209206cd13c",
        "TypeName": "Grooper.Core.DocumentType"
      },
      {
        "Id": "52130f97-a419-4ef8-8c41-aaf83a9c555a",
        "Name": "Data Change",
        "NodeIndex": 3,
        "NumChildren": 2,
        "ParentId": "bc22effb-0db9-4d1e-9665-2209206cd13c",
        "TypeName": "Grooper.Core.DocumentType"
      },
      {
        "Id": "95e52a6b-b7b3-4ef9-a068-9f18bb06e1e9",
        "Name": "Data Info",
        "NodeIndex": 4,
        "NumChildren": 1,
        "ParentId": "bc22effb-0db9-4d1e-9665-2209206cd13c",
        "TypeName": "Grooper.Core.DocumentType"
      }
    ]
  }
]

GetFolderInfo: Get info for a single Batch Folder

GET {baseUrl}/api/v1/BatchProcessing/Folders/{FolderId}


This will will return information about the folder. Enter a Batch Folder's GUID to return information about it.

  • Notably, its "Name" and "DataIsValid" value are often of use.


Example JSON response if the folder exists: 

{
  "Id": "32cddd2f-dd3c-486b-b6f3-1bcd3045510b",
  "Name": "Generic Invoice (2)",
  "NodeIndex": 1,
  "NumChildren": 1,
  "ParentId": "8610db0f-637c-4174-afb2-23dc7ace05bf",
  "TypeName": "Grooper.Core.BatchFolder",
  "Attachment": "04.pdf",
  "DataIsValid": false,
  "JsonData": "Grooper.DocumentData.json",
  "MimeType": "application/pdf",
  "PdfVersion": "Grooper.PdfVersion.pdf",
  "TypeId": "05b74bdd-1d09-4c73-afd1-b591040e367c",
  "XmlData": "Grooper.DocumentData.xml"
}


Example JSON response if an invalid GUID is provided (i.e. the object whose GUID you summited is not a folder): 

{
  "Message": "Object with ID '74b475a5-fc58-4e6d-b737-b94f6d0aed4c' is not a Batch Folder."
}


Example JSON response if the folder is not found (i.e. the folder has been deleted or never existed in the first place): 

{
  "Message": "Batch Folder with ID '79aa46db-cc9c-4ee0-b15d-0c369b603910' not found."
}

GetFolders: Get info for all Batch Folders (at a specific level)

GET {baseUrl}/api/v1/BatchProcessing/Folders/{ParentId}/Folders?Level={Level}


This request will return information about all folders at a specified level within a specified folder. Enter the GUID for any parent folder (such as a Batch's root folder's GUID) and the folder level you want to search.

  • You will receive information about all folders at that level, including their GUID id, names, index, "DataIsValid" values and more.
  • In this example, {ParentId} was set to the GUID for a Batch's root folder, and we entered 1 for the Level.
  • There were three total Batch Folders at that level. Information for all three was returned in the JSON response.

See below for an example JSON response: 

[
  {
    "Id": "899b9bf6-59b5-4267-97a8-f7e129d560d9",
    "Name": "Fairdeal (1)",
    "NodeIndex": 0,
    "NumChildren": 1,
    "ParentId": "54c49476-521a-4ad1-b5cc-56c616efe9f9",
    "TypeName": "Grooper.Core.BatchFolder",
    "Attachment": "01.pdf",
    "DataIsValid": true,
    "JsonData": "Grooper.DocumentData.json",
    "MimeType": "application/pdf",
    "PdfVersion": "Grooper.PdfVersion.pdf",
    "TypeId": "0857ae20-bb46-4d56-8943-ddd9156a69e4",
    "XmlData": "Grooper.DocumentData.xml"
  },
  {
    "Id": "05339601-e2d5-457e-9e6a-b212e838711d",
    "Name": "nama (2)",
    "NodeIndex": 1,
    "NumChildren": 1,
    "ParentId": "54c49476-521a-4ad1-b5cc-56c616efe9f9",
    "TypeName": "Grooper.Core.BatchFolder",
    "Attachment": "02.pdf",
    "DataIsValid": true,
    "JsonData": "Grooper.DocumentData.json",
    "MimeType": "application/pdf",
    "PdfVersion": "Grooper.PdfVersion.pdf",
    "TypeId": "8cc37157-132f-4618-8a08-0f2aa4b9153b",
    "XmlData": "Grooper.DocumentData.xml"
  },
  {
    "Id": "73a7ed14-61c1-48fc-8caf-8ba7a2ee0cc3",
    "Name": "Folder (3)",
    "NodeIndex": 2,
    "NumChildren": 1,
    "ParentId": "54c49476-521a-4ad1-b5cc-56c616efe9f9",
    "TypeName": "Grooper.Core.BatchFolder",
    "DataIsValid": false
  }
]

GetMetadata: Get extracted results for a document (single instance Data Fields only)

GET {baseUrl}/api/v1/BatchProcessing/Folders/{FolderId}/Metadata


This request returns extracted data for a Batch Folder. Enter a Batch Folder's GUID and you will return two things:

  1. The Batch Folder's "ContentTypeId" value (This is its Document Type's GUID).
  2. A list of key-value pairs for each single instance field extracted for the document.
    • For example, if you extracted a value (000-00-0000) for a "Social Sec Num" field you would see something like the following:
"FieldValues": [
  {
    "Key": "Social_Sec_Num",
    "Value": "000-00-0000"
  }
]
  • Note: "Key" names for Data Fields in single instance Data Sections are returned using dot notation (e.g. "DataSectionName.DataFieldName")

See below for an example response: 

{
  "ContentTypeId": "8cc37157-132f-4618-8a08-0f2aa4b9153b",
  "FieldValues": [
    {
      "Key": "GUID",
      "Value": "30cbbb98-bada-407d-aaca-573748e31350"
    },
    {
      "Key": "Header_Details.Invoice_Number",
      "Value": "#PBJ001"
    },
    {
      "Key": "Header_Details.Invoice_Date",
      "Value": "10/19/2009"
    },
    {
      "Key": "Header_Details.Invoice_Total",
      "Value": "688.98"
    }
  ]
}

GetPages: Get info about Batch Pages (can optionally be recursive)

GET {baseUrl}/api/v1/BatchProcessing/Folders/{ParentId}/Pages?Recursive={Recursive}


This request returns information about pages in a folder. Enter the GUID for a Batch Folder and either "true" or "false" to indicate if the search is recursive.

  • For the recursive parameter, enter:
    • True if you want all pages from all levels below the Batch Folder
    • False if you want only pages at the given Batch Folder level.


Example when {Recursive} is False.

  • Here, there was only a single page at the selected Batch Folder's level.


Example JSON response when {Recursive} is False. 

[
  {
    "Id": "afa2699d-6f71-40d1-9a33-0a3a8a233772",
    "Name": "Page 2",
    "NodeIndex": 1,
    "NumChildren": 0,
    "ParentId": "7d7984d4-ac9f-4742-9dfe-31e96311e403",
    "TypeName": "Grooper.Core.BatchPage",
    "DisplayImage": null,
    "Height": 11,
    "OriginalPageNo": 0,
    "PixelFormat": 0,
    "PrimaryImage": "Grooper.Image.pdf",
    "Width": 8.5
  }
]

Example when {Recursive} is True.

  • Here, there are two pages. One is at level 1 and the other at level 2.


Example JSON response when {Recursive} is False. 

[
  {
    "Id": "a5502938-e76e-40e4-a8eb-8f4e44651617",
    "Name": "Page 1",
    "NodeIndex": 0,
    "NumChildren": 0,
    "ParentId": "74df0ea0-6225-4cc8-ae19-316906c3d017",
    "TypeName": "Grooper.Core.BatchPage",
    "DisplayImage": null,
    "Height": 11,
    "OriginalPageNo": 0,
    "PixelFormat": 0,
    "PrimaryImage": "Grooper.Image.pdf",
    "Width": 8.5
  },
  {
    "Id": "afa2699d-6f71-40d1-9a33-0a3a8a233772",
    "Name": "Page 2",
    "NodeIndex": 1,
    "NumChildren": 0,
    "ParentId": "7d7984d4-ac9f-4742-9dfe-31e96311e403",
    "TypeName": "Grooper.Core.BatchPage",
    "DisplayImage": null,
    "Height": 11,
    "OriginalPageNo": 0,
    "PixelFormat": 0,
    "PrimaryImage": "Grooper.Image.pdf",
    "Width": 8.5
  }
]

GetProcess: Get information about a published Batch Process

GET {baseUrl}/api/v1/BatchProcessing/Process?Process={Process}


This will return information about a published Batch Process, including information about each of its child steps.

You may enter one of the following for the {Process} parameter:

  • The published Batch Process's name.
  • A working Batch Process's Id (GUID).
    • PLEASE NOTE: The process must be published to return information using the working version's Id.
    • You will return information about the current published version in either case.

Example when entering the published Batch Process's name.

Example when entering the working Batch Process's GUID.

Notice the API response results are the same.

Example JSON Response: 

{
  "Id": "f2132f81-eb1a-42c4-894e-441cb667b60c",
  "Name": "Info Sheet - GetProcess",
  "NodeIndex": 0,
  "NumChildren": 6,
  "ParentId": "b42eb137-326c-4bc0-9b05-048d01673ff9",
  "TypeName": "Grooper.Core.BatchProcess",
  "ParentProcessId": "ee474154-5589-4215-958a-c0e618ce3fbd",
  "PublishedDate": "/Date(1713446671000-0500)/",
  "Steps": [
    {
      "Id": "24141f94-de2a-4747-9566-68fbccda0abf",
      "Name": "Scan",
      "NodeIndex": 0,
      "NumChildren": 0,
      "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
      "TypeName": "Grooper.Core.BatchProcessStep",
      "ActivateMode": 0,
      "ActivityType": "Grooper.Activities.Review",
      "FolderLevel": 1,
      "NextStepExpression": "",
      "Scope": 1,
      "ShouldSubmitExpression": "",
      "ThreadPool": null
    },
    {
      "Id": "9490a661-d41a-43b1-95e4-3e1418631302",
      "Name": "Image Processing",
      "NodeIndex": 1,
      "NumChildren": 0,
      "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
      "TypeName": "Grooper.Core.BatchProcessStep",
      "ActivateMode": 0,
      "ActivityType": "Grooper.Activities.ImageProcessing",
      "FolderLevel": 1,
      "NextStepExpression": "",
      "Scope": 3,
      "ShouldSubmitExpression": "",
      "ThreadPool": null
    },
    {
      "Id": "340ddff7-7a12-4739-89f2-ce211997cfb6",
      "Name": "Recognize",
      "NodeIndex": 2,
      "NumChildren": 0,
      "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
      "TypeName": "Grooper.Core.BatchProcessStep",
      "ActivateMode": 0,
      "ActivityType": "Grooper.Activities.Recognize",
      "FolderLevel": 1,
      "NextStepExpression": "",
      "Scope": 3,
      "ShouldSubmitExpression": "",
      "ThreadPool": null
    },
    {
      "Id": "4fdec9ec-44d8-4bb7-be00-b4530cf32b67",
      "Name": "Extract",
      "NodeIndex": 3,
      "NumChildren": 0,
      "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
      "TypeName": "Grooper.Core.BatchProcessStep",
      "ActivateMode": 0,
      "ActivityType": "Grooper.Activities.Extraction",
      "FolderLevel": 1,
      "NextStepExpression": "",
      "Scope": 2,
      "ShouldSubmitExpression": "",
      "ThreadPool": null
    },
    {
      "Id": "99c3c68a-311e-456b-9bfe-d0373274b351",
      "Name": "Review",
      "NodeIndex": 4,
      "NumChildren": 0,
      "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
      "TypeName": "Grooper.Core.BatchProcessStep",
      "ActivateMode": 0,
      "ActivityType": "Grooper.Activities.Review",
      "FolderLevel": 1,
      "NextStepExpression": "",
      "Scope": 1,
      "ShouldSubmitExpression": "",
      "ThreadPool": null
    },
    {
      "Id": "513abcd2-55c9-46d9-8ddb-04562a81a997",
      "Name": "Export",
      "NodeIndex": 5,
      "NumChildren": 0,
      "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
      "TypeName": "Grooper.Core.BatchProcessStep",
      "ActivateMode": 0,
      "ActivityType": "Grooper.Activities.Export",
      "FolderLevel": 1,
      "NextStepExpression": "",
      "Scope": 2,
      "ShouldSubmitExpression": "",
      "ThreadPool": null
    }
  ]
}


Error response when an invalid Batch Process name is passed:

  • You will get this error if no published Batch Process with that name exists.
{
  "Message": "Invalid Published Process Name."
}


Error response when an invalid Batch Process GUID is passed:

  • You will get this error if the working Batch Process does not exist.
  • You will get this error if the working Batch Process is not published.
  • You will get this error when entering a published Batch Process's GUID.
{
  "Message": "Invalid Working Process Id."
}

GetProcesses: Get a list of all published Batch Processes

GET {baseUrl}/api/v1/BatchProcessing/Processes?Verbose={Verbose}


This returns a list of all published Batch Processes. You must enter True or False for {Verbose}

  • Verbose=False will return a simple list of published Batch Processes and some information about them (Their "Id", "Name", "ParentId" and more).
  • Verbose=True will return a nested list of published Batch Processes and information about about each of their steps.


Example when using Verbose=False

  • In this example, only two Batch Processes in the repo are published.
  • The API returns just information about the Batch Processes not their steps.

Example when using Verbose=True

  • In this example, only two Batch Processes in the repo are published.
  • The API returns information about the Batch Processes and their steps.

Example JSON response when {Verbose} is False

[ 

 {
   "Id": "f2132f81-eb1a-42c4-894e-441cb667b60c",
   "Name": "Info Sheet - GetProcess",
   "NodeIndex": 0,
   "NumChildren": 6,
   "ParentId": "b42eb137-326c-4bc0-9b05-048d01673ff9",
   "TypeName": "Grooper.Core.BatchProcess",
   "ParentProcessId": "ee474154-5589-4215-958a-c0e618ce3fbd",
   "PublishedDate": "/Date(1713446671000-0500)/",
   "Steps": null
 },
 {
   "Id": "0cab9642-7f1f-4192-bab5-48f8823feae1",
   "Name": "Invoices Simple - GetProcesses",
   "NodeIndex": 1,
   "NumChildren": 7,
   "ParentId": "b42eb137-326c-4bc0-9b05-048d01673ff9",
   "TypeName": "Grooper.Core.BatchProcess",
   "ParentProcessId": "a0f4898d-d6e9-4bb4-a99c-b382f2b4ad16",
   "PublishedDate": "/Date(1713286468000-0500)/",
   "Steps": null
 }

]


Example JSON response when {Verbose} is True

[ 

 {
   "Id": "f2132f81-eb1a-42c4-894e-441cb667b60c",
   "Name": "Info Sheet - GetProcess",
   "NodeIndex": 0,
   "NumChildren": 6,
   "ParentId": "b42eb137-326c-4bc0-9b05-048d01673ff9",
   "TypeName": "Grooper.Core.BatchProcess",
   "ParentProcessId": "ee474154-5589-4215-958a-c0e618ce3fbd",
   "PublishedDate": "/Date(1713446671000-0500)/",
   "Steps": [
     {
       "Id": "24141f94-de2a-4747-9566-68fbccda0abf",
       "Name": "Scan",
       "NodeIndex": 0,
       "NumChildren": 0,
       "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Review",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 1,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "9490a661-d41a-43b1-95e4-3e1418631302",
       "Name": "Image Processing",
       "NodeIndex": 1,
       "NumChildren": 0,
       "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.ImageProcessing",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 3,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "340ddff7-7a12-4739-89f2-ce211997cfb6",
       "Name": "Recognize",
       "NodeIndex": 2,
       "NumChildren": 0,
       "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Recognize",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 3,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "4fdec9ec-44d8-4bb7-be00-b4530cf32b67",
       "Name": "Extract",
       "NodeIndex": 3,
       "NumChildren": 0,
       "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Extraction",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 2,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "99c3c68a-311e-456b-9bfe-d0373274b351",
       "Name": "Review",
       "NodeIndex": 4,
       "NumChildren": 0,
       "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Review",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 1,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "513abcd2-55c9-46d9-8ddb-04562a81a997",
       "Name": "Export",
       "NodeIndex": 5,
       "NumChildren": 0,
       "ParentId": "f2132f81-eb1a-42c4-894e-441cb667b60c",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Export",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 2,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     }
   ]
 },
 {
   "Id": "0cab9642-7f1f-4192-bab5-48f8823feae1",
   "Name": "Invoices Simple - GetProcesses",
   "NodeIndex": 1,
   "NumChildren": 7,
   "ParentId": "b42eb137-326c-4bc0-9b05-048d01673ff9",
   "TypeName": "Grooper.Core.BatchProcess",
   "ParentProcessId": "a0f4898d-d6e9-4bb4-a99c-b382f2b4ad16",
   "PublishedDate": "/Date(1713286468000-0500)/",
   "Steps": [
     {
       "Id": "bb475d56-a81d-4bfe-85dd-fdda20a90b74",
       "Name": "Split Pages",
       "NodeIndex": 0,
       "NumChildren": 0,
       "ParentId": "0cab9642-7f1f-4192-bab5-48f8823feae1",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.SplitPages",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 2,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "f9de8903-80b1-4a8b-bc64-46f8d71528ca",
       "Name": "Recognize",
       "NodeIndex": 1,
       "NumChildren": 0,
       "ParentId": "0cab9642-7f1f-4192-bab5-48f8823feae1",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Recognize",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 3,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "07b7ec72-f8f7-459f-9671-2320118c34de",
       "Name": "Classify",
       "NodeIndex": 2,
       "NumChildren": 0,
       "ParentId": "0cab9642-7f1f-4192-bab5-48f8823feae1",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.ClassifyFolders",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 2,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "14e041d9-cb92-4d97-8a6c-71fe41656105",
       "Name": "Classify Review",
       "NodeIndex": 3,
       "NumChildren": 0,
       "ParentId": "0cab9642-7f1f-4192-bab5-48f8823feae1",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Review",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 1,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "07d28653-c613-4e0c-9f50-7d5e4bf20e50",
       "Name": "Extract",
       "NodeIndex": 4,
       "NumChildren": 0,
       "ParentId": "0cab9642-7f1f-4192-bab5-48f8823feae1",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Extraction",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 2,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "182d71f4-8e0a-4896-a0cd-761a289dcc3a",
       "Name": "Extract Review",
       "NodeIndex": 5,
       "NumChildren": 0,
       "ParentId": "0cab9642-7f1f-4192-bab5-48f8823feae1",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Review",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 1,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     },
     {
       "Id": "c42c6929-b8e8-4c1f-bae3-2eba1261d876",
       "Name": "Export",
       "NodeIndex": 6,
       "NumChildren": 0,
       "ParentId": "0cab9642-7f1f-4192-bab5-48f8823feae1",
       "TypeName": "Grooper.Core.BatchProcessStep",
       "ActivateMode": 0,
       "ActivityType": "Grooper.Activities.Export",
       "FolderLevel": 1,
       "NextStepExpression": "",
       "Scope": 2,
       "ShouldSubmitExpression": "",
       "ThreadPool": null
     }
   ]
 }

]

PauseBatch: Pause a Batch

GET {baseUrl}/api/v1/BatchProcessing/Batches/{BatchId}/Pause


This request will pause a Batch in production. Enter the Batch's GUID to pause it.

  • The JSON response will be property information about the Batch.
  • Note the Status value in the JSON response is 4.
    • A status of "4" indicates the Batch is "paused" (Prevents tasks from processing until the Batch is un-paused/started/resumed).
    • A status of "1" indicates the Batch is "ready" (A Review task is ready to be processed).
    • A status of "2" indicates the Batch is "working" (Tasks are actively being processed).
    • A status of "3" indicates the Batch is "completed" (All tasks for all steps have finished processing).
    • A status of "5" indicates the Batch is in "error"
    • A status of "6" indicates the Batch is "cancelled"


See below for an example response: 

{
  "Id": "2f15234b-7f90-4aa1-aaca-8c663598eb3a",
  "Name": "Info Sheets 2023-03-22 09:06:54 AM",
  "NodeIndex": 0,
  "NumChildren": 2,
  "ParentId": "d32eda1b-5b42-441b-a6d5-a4018080b433",
  "TypeName": "Grooper.Core.Batch",
  "Created": "/Date(1679494027613-0500)/",
  "CreatedBy": "BIS\\dgreenwood",
  "Priority": 3,
  "RootFolderId": "5edf03f7-e671-4099-a120-62221acc2d1d",
  "Status": 4,
  "StepNo": 4
}

StartBatch: Start/resume processing on a Batch

GET {baseUrl}/api/v1/BatchProcessing/Batches/{BatchId}/Start


This request will start processing a Batch (or otherwise resume processing for a paused Batch). Enter a Batch's GUID to start processing it.

  • The JSON response will be property information about the Batch.
  • The "Status" value in the JSON response should be "1" (Ready) when starting on a Review step and "2" (Working) for all other Activities.
    • A status of "1" indicates the Batch is "ready" (A Review task is ready to be processed).
    • A status of "2" indicates the Batch is "working" (Tasks are actively being processed).
    • A status of "3" indicates the Batch is "completed" (All tasks for all steps have finished processing).
    • A status of "4" indicates the Batch is "paused" (Prevents tasks from processing until the Batch is un-paused/started/resumed).
    • A status of "5" indicates the Batch is in "error"
    • A status of "6" indicates the Batch is "cancelled"


See below for an example response: 

{
  "Id": "2f15234b-7f90-4aa1-aaca-8c663598eb3a",
  "Name": "Info Sheets 2023-03-22 09:06:54 AM",
  "NodeIndex": 0,
  "NumChildren": 2,
  "ParentId": "d32eda1b-5b42-441b-a6d5-a4018080b433",
  "TypeName": "Grooper.Core.Batch",
  "Created": "/Date(1679494027613-0500)/",
  "CreatedBy": "BIS\\dgreenwood",
  "Priority": 3,
  "RootFolderId": "5edf03f7-e671-4099-a120-62221acc2d1d",
  "Status": 1,
  "StepNo": 4
}

CreateBatch: Create a new Batch

POST {baseUrl}/api/v1/BatchProcessing/Processes/{ProcessName}/CreateBatch?BatchName={BatchName}


This request will create a new Batch in Grooper. This request has one required parameter and two optional parameters.

  • Required Parameters
    • You must enter a published Batch Process name for {ProcessName}
  • Optional Parameters
    • You may enter a name for the Batch by editing the {BatchName}. If this parameter is left blank, the Batch will be named with a timestamp (date/time created).
    • You may enter Batch level Data Field values in JSON format.
      • The published Batch Process must have a Content Type assigned to it with corresponding Data Elements in its Data Model or you will get an error.
      • Batch level Data Fields are used to capture information about the whole Batch (rather than information for each individual document)

BE AWARE: Batches created using the CreateBatch endpoint are always created in a paused state. You will need to use the StartBatch endpoint to start processing after creating the Batch.


Example 1: Creating a Batch with an optional {BatchName} but without optional Data Field values.

  • This is the most common scenario.
  • Using the {ProcessName} parameter, enter the name of the Batch Process you wish to execute. Be sure to use the published version's name.
  • Using the {BatchName} parameter, enter a name for the Batch.


Example 2: Creating a Batch with optional Data Field values.

  • This is less common.
  • Batch level Data Fields are used to capture information about the whole Batch (rather than information for each individual document).
    • This could store an indexing id for the Batch.
    • This could store a name for the user creating the Batch.
    • A common scenario for Batch level fields comes from the world of document imaging. Scan operators will save a number identifying the box of pages they are scanning and who scanned the pages to Data Fields on the Batch. This information can be used further down the road if a problem is identified and pages need to be rescanned.
  • Be aware, these values must have someplace to go. The Batch Process used to create the Batch must have its Content Type property configured.

In our example, our process's Content Type property references "Cow Apps".

"Cow Apps" is a Content Model. Its Data Model has two Data Fields:

  • "ID Number"
  • "Prepared By"

Either of these fields could be populated by the CreateBatch endpoint in this scenario

  • Data Field values are uploaded using the following JSON format, where "Key" is the Data Field's name and "Value" is the value you want to store:
    • Note spaces and special characters must be replaced by underscores.
    • Note
{
  "FieldValues": [
    {
      "Key": "Data_Field_1",
      "Value": "Value for Data Field 1"
    }
    {
      "Key": "DataField2",
      "Value": "Value for Data Field 2"
    }
  ]
}
Retrieved from "https://wiki.grooper.com/index.php?title=2023:API_Services_(Service)&oldid=21639"