2023.1:API Services (Service)

From Grooper Wiki

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 inventory_2 Batch processing via REST API web calls by installing API Services.

  • As of version 2025, the Grooper Web Services (GWS) web app hosts additional API endpoints. Some of these endpoints overlap with the API Services endpoints. Refer to the GWS documentation for more information on its endpoint offerings. You can locate the GWS documentation for your Grooper install at https://{webserver-name-or-domain-name}/GWS

You may download the ZIP(s) below and upload it into your own Grooper environment (version 2023.1). The first contains one or more Batches of sample documents. The second contains one or more Projects with resources used in examples throughout this article.

While there are no "How To" tutorials in this article, you can use the resources in these ZIPs to test the Grooper REST API.

Glossary

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

  • As of version 2025, the Grooper Web Services (GWS) web app hosts additional API endpoints. Some of these endpoints overlap with the API Services endpoints. Refer to the GWS documentation for more information on its endpoint offerings. You can locate the GWS documentation for your Grooper install at https://{webserver-name-or-domain-name}/GWS

Service: Grooper Services are various executable programs that run as a Windows Service to facilitate Grooper processing. Service instances are installed, configured, started and stopped using Grooper Command Console (or in older Grooper versions, Grooper Config).

Batch: inventory_2 Batch nodes are fundamental in Grooper's architecture. They are containers of documents that are moved through workflow mechanisms called settings Batch Processes. Documents and their pages are represented in Batches by a hierarchy of folder Batch Folders and contract Batch Pages.

Project: package_2 Projects are the primary containers for configuration nodes within Grooper. The Project is where various processing objects such as stacks Content Models, settings Batch Processes, profile objects are stored. This makes resources easier to manage, easier to save, and simplifies how node references are made in a Grooper Repository.

Batch Process: settings Batch Process nodes are crucial components in Grooper's architecture. A Batch Process is the step-by-step processing instructions given to a inventory_2 Batch. Each step is comprised of a "Code Activity" or a Review activity. Code Activities are automated by Activity Processing services. Review activities are executed by human operators in the Grooper user interface.

  • Batch Processes by themselves do nothing. Instead, they execute edit_document Batch Process Steps which are added as children nodes.
  • A Batch Process is often referred to as simply a "process".

Batch Folder: The folder Batch Folder is an organizational unit within a inventory_2 Batch, allowing for a structured approach to managing and processing a collection of documents. Batch Folder nodes serve two purposes in a Batch. (1) Primarily, they represent "documents" in Grooper. (2) They can also serve more generally as folders, holding other Batch Folders and/or contract Batch Page nodes as children.

  • Batch Folders are frequently referred to simply as "documents" or "folders" depending on how they are used in the Batch.

Repository: A "repository" is a general term in computer science referring to where files and/or data is stored and managed. In Grooper, the term "repository" may refer to:

Grooper Service:

Execute: tv_options_edit_channels Execute is an Activity that runs one or more specified object commands. This gives access to a variety of Grooper commands in a settings Batch Process for which there is no Activity, such as the "Sort Children" command for Batch Folders or the "Expand Attachments" command for email attachments.

Root: The Grooper database Root node is the topmost element of the Grooper Repository. All other nodes in a Grooper Repository are its children/descendants. The Grooper Root also stores several settings that apply to the Grooper Repository, including the license serial number or license service URL and Repository Options.

Grooper Repository: A Grooper Repository is the environment used to create, configure and execute objects in Grooper. It provides the framework to "do work" in Grooper. Fundamentally, a Grooper Repository is a connection to a database and file store location, which store the node configurations and their associated file content. The Grooper application interacts with the Grooper Repository to automate tasks and provide the Grooper user interface.

Batch Page: contract Batch Page nodes represent individual pages within a inventory_2 Batch. Batch Pages are created in one of two ways: (1) When images are scanned into a Batch using the Scan Viewer. (2) Or, when split from a PDF or TIFF file using the Split Pages activity.

  • Batch Pages are frequently referred to simply as "pages".

File Store: hard_drive File Store nodes are a key part of Grooper's "database and file store" architecture. They define a storage location where file content associated with Grooper nodes are saved. This allows processing tasks to create, store and manipulate content related to documents, images, and other "files".

  • Not every node in Grooper will have files associated with it, but if it does, those files are stored in the Windows folder location defined by the File Store node.

Data Model: data_table Data Models are leveraged during the Extract activity to collect data from documents (folder Batch Folders). Data Models are the root of a Data Element hierarchy. The Data Model and its child Data Elements define a schema for data present on a document. The Data Model's configuration (and its child Data Elements' configuration) define data extraction logic and settings for how data is reviewed in a Data Viewer.

Content Type: Content Types are a class of node types used used to classify folder Batch Folders. They represent categories of documents (stacks Content Models and collections_bookmark Content Categories) or distinct types of documents (description Document Types). Content Types serve an important role in defining Data Elements and Behaviors that apply to a document.

Content Model: stacks Content Model nodes define a classification taxonomy for document sets in Grooper. This taxonomy is defined by the collections_bookmark Content Categories and description Document Types they contain. Content Models serve as the root of a Content Type hierarchy, which defines Data Element inheritance and Behavior inheritance. Content Models are crucial for organizing documents for data extraction and more.

Document Type: description Document Type nodes represent a distinct type of document, such as an invoice or a contract. Document Types are created as child nodes of a stacks Content Model or a collections_bookmark Content Category. They serve three primary purposes:

  1. They are used to classify documents. Documents are considered "classified" when the folder Batch Folder is assigned a Content Type (most typically, a Document Type).
  2. The Document Type's data_table Data Model defines the Data Elements extracted by the Extract activity (including any Data Elements inherited from parent Content Types).
  3. The Document Type defines all "Behaviors" that apply (whether from the Document Type's Behavior settings or those inherited from a parent Content Type).

Data Field: variables Data Fields represent a single value targeted for data extraction on a document. Data Fields are created as child nodes of a data_table Data Model and/or insert_page_break Data Sections.

  • Data Fields are frequently referred to simply as "fields".

Data Section: A insert_page_break Data Section is a container for Data Elements in a data_table Data Model. variables They can contain Data Fields, table Data Tables, and even Data Sections as child nodes and add hierarchy to a Data Model. They serve two main purposes:

  1. They can simply act as organizational buckets for Data Elements in larger Data Models.
  2. By configuring its "Extract Method", a Data Section can subdivide larger and more complex documents into smaller parts to assist in extraction.
    • "Single Instance" sections define a division (or "record") that appears only once on a document.
    • "Multi-Instance" sections define collection of repeating divisions (or "records").

Extract: export_notes Extract is an Activity that retrieves information from folder Batch Folder documents, as defined by Data Elements in a data_table Data Model. This is how Grooper locates unstructured data on your documents and collects it in a structured, usable format.

Activity: Grooper Activities define specific document processing operations done to a inventory_2 Batch, folder Batch Folder, or contract Batch Page. In a settings Batch Process, each edit_document Batch Process Step executes a single Activity (determined by the step's "Activity" property).

  • Batch Process Steps are frequently referred by the name of their configured Activity followed by the word "step". For example: "Classify step".

Review: person_search Review is an Activity that allows user attended review of Grooper's results. This allows human operators to validate processed contract Batch Page and folder Batch Folder content using specialized user interfaces called "Viewers". Different kinds of Viewers assist users in reviewing Grooper's image processing, document classification, data extraction and operating document scanners.

Scope: The Scope property of a edit_document Batch Process Step, as it relates to an Activity, determines at which level in a inventory_2 Batch hierarchy the Activity runs.

Thread: A Thread is the smallest unit of processing that can be performed within an operating system. In Grooper, threads are allocated for processing by Activity Processing services.

Image Processing: wallpaper Image Processing is an Activity that enhances contract Batch Page images and optimizes them for better OCR text recognition and data extraction results.

Image Processing: "Image processing", as a general term, refers to software techniques that manipulate and enhance images. Image processing removes imperfections and adjusts images to improve OCR accuracy. In Grooper, images are processed primarily by two Activities:

  • Image Processing - This Activity permanently adjusts the image using. It is primarily used to compensate for defects produced by a document scanner (like border artifacts and skewed images). It does so by applying IP Commands in an perm_media IP Profile.
  • Recognize - This Activity performs OCR. When an library_books OCR Profile references an perm_media IP Profile, the image will be processed temporarily. A temporary image is handed to the OCR engine and discarded once characters are recognized.
  • Grooper also has "computer vision" capabilities that analyze and interpret images. These capabilities are also executed during Grooper's image processing. For example, Grooper's "Line Removal" command will locate lines on an image (computer vision), remove those artifacts to improve OCR results during Recognize (image processing) and store that data for later use in Grooper (computer vision).

Recognize: format_letter_spacing_wide Recognize is an Activity that obtains machine-readable text from contract Batch Pages and folder Batch Folders. When properly configured with an library_booksOCR Profile, Recognize will selectively perform OCR for images and native-text extraction for digital text in PDFs. Recognize can also reference an perm_mediaIP Profile to collect "layout data" like lines, checkboxes, and barcodes. Other Activities then use this machine-readable text and layout data for document analysis and data extraction.

Export: output Export is an Activity that transfers documents and extracted information to external file systems and content management systems, completing the data processing workflow.

Split Pages: Multi-page PDF and TIF files come into Grooper as files attached to single folder Batch Folders. Split Pages is an Activity that creates child contract Batch Pages for each page in the PDF or TIF. This allows Grooper to process and handle these pages as individual objects.

Split: Split is a Collation Provider option for pin Data Type extractors. Split separates a data instance at each match returned by the Data Type. The results are used as anchor points to "split" text into one or more smaller parts.

Classify: unknown_document Classify is an Activity that "classifies" folder Batch Folders in a inventory_2 Batch by assigning them a description Document Type.

  • Classification is key to Grooper's document processing. It affects how data is extracted from a document (during the Extract activity) and how Behaviors are applied.
  • Classification logic is controlled by a Content Model's "Classify Method". These methods include using text patterns, previously trained document examples, and Label Sets to identify documents.

Data Element: Data Elements are a class of node types used to collect data from a document. These include: data_table Data Models, insert_page_break Data Sections, variables Data Fields, table Data Tables, and view_column Data Columns.

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

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 a Batch's ID (GUID).

⚠

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.

If you suspect an endpoint you are testing is using a cached value (or otherwise are getting a result you aren't expecting), try refreshing your web browser.

BE AWARE: 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.


The DeleteBatch endpoint has one required parameter.

  • Required Parameters
    • {BatchId}: Enter the ID (GUID) for the Batch you want to delete.


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.

  • Returned information includes its "Id", "Name", "Status" and more property values).


The GetBatchInfo endpoint has one required parameter:

  • Required Parameters
    • {BatchId}: Enter the Batch's ID (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}

This request returns information about all production Batches in a Grooper Repository at a specified level.


The GetBatchInfos request has one required parameter.

  • Required Parameters:
    • {Level}: Enter an integer for the level of the Batches > Production folder you want to query.
      • Entering Level=0 will return information about all production Batches at all folder levels.
      • Entering any other number will only return information about Batches at that folder level.


In this example, we enter 0 for the {Level}. This returns information about all production Batches at all levels.

  • This is the most common request but can be computationally inefficient as Grooper must iterate 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. 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.


The GetContentStream endpoint has two required parameters.

  • Required Parameters
    • {ItemId}: Enter the ID (GUID) for a Batch Folder or Batch Page in Grooper.
      • This must be a node in Grooper that has a file in the file store.
      • Most commonly a Batch Folder's ID
      • Less commonly a Batch Page's ID
    • {FileName}: Enter the file's name.
      • Most commonly a file associated with a Batch Folder in the Grooper File Store.
      • Less commonly a file associated with a Batch Page in the Grooper File Store.


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.


The GetContentTypes endpoint has no parameters.

  • 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 request gives information about a folder. It will return property details for a Batch Folder.

  • Returned data includes its "Name", "Attachment", "TypeId" (its Content Type's ID), "DataIsValid" values and more.


The GetFolderInfo has one required parameter.

  • Required Parameters
    • {FolderId}: Enter a Batch Folder's ID (GUID) to return information about it.


In this example, we returned information from a processed invoice document in Grooper.


Example JSON response if the Batch 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 Batch 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 gives information about one or more folders at a defined level in a Batch. It will return information about all Batch Folders at a specified level in the tree hierarchy within the entered Batch Folder.


The GetFolders endpoint has two required parameters.

  • Required Parameters
    • {ParentId}: Enter the parent folder's ID (GUID) for any parent folder you want to search in.
    • {Level}: Enter an integer for the folder level you want to search.
      • You will receive information about all folders at that level.
      • This includes their "ID", "Name", "TypeId", "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 data Grooper extracted for a document (Batch Folder).

Two things are returned:

  1. A "ContentTypeId" value for the document (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: Spaces and special characters in Data Field names are replaced by underscores in the "Key" names.
  • Note: "Key" names for Data Fields in single instance Data Sections are returned using dot notation (e.g. "DataSectionName.DataFieldName")


The GetMetadata endpoint has one required parameter.

  • Required Parameters:
    • {FolderId}: Enter the ID (GUID) for the Batch Folder whose extracted data you want to return.


In this example, the GetMetadata request returned extracted data from an invoice document that Grooper collected during an Extract step of a Batch Process.

See below for an example response: 

{
  "ContentTypeId": "8cc37157-132f-4618-8a08-0f2aa4b9153b",
  "FieldValues": [
    {
      "Key": "UniqueID",
      "Value": "2bd049a5-88a7-499d-9f2c-dff7cd65f2e7"
    },
    {
      "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 Batch Pages in a folder. Pages can be queried recursively or non-recursively.


The GetPages endpoint has two required parameters.

  • Required Parameters
    • {ParentId}: Enter the ID (GUID) for the Batch Folder containing the pages.
    • {Recursive}: Enter True or False to indicate if the search is recursive.
      • 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=False:

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


Example JSON response when Recursive=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=True:

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


Example JSON response when Recursive=True: 

[
  {
    "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.


The GetProcess endpoint has one required parameter.

  • Required Parameters:
    • {Process}: Enter either:
      • 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.


The GetProcesses endpoint has one required parameter.

  • Required Parameters
    • {Verbose}: You must enter True or False for this parameter.
      • 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.


The PauseBatch endpoint has one required parameter.

  • Required Parameters
    • {BatchId}: Enter the Batch's ID (GUID) to pause it.


The JSON response will be property information about the Batch. The "Status" value in the JSON response should be "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"

In our example below, see we paused a Batch. So, the "Status" is "4".


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).


The StartBatch endpoint has one required parameter.

  • Required Parameters
    • {BatchId}: Enter a Batch's ID (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"

In our example below, see we started a Batch, and its first step was a Review step. So, the "Status" is "1".


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 CreateBatch endpoint has one required parameter and two optional parameters.

  • Required Parameters
    • {ProcessName}: You must enter a published Batch Process name.
      • This is the Batch Process you want to use to process the Batch and its contents.
      • Be sure to enter the published version's name.
  • Optional Parameters
    • {BatchName}: You may optionally enter a name for the Batch.
      • If this parameter is left blank, the Batch will be named with a timestamp (date/time created).
    • "FieldValues": You may optionally enter Batch level Data Field values in a JSON format.
      • Batch level Data Fields are used to capture information about the whole Batch (rather than information for each individual document)
      • 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.
      • 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.
{
  "FieldValues": [
    {
      "Key": "Data_Field_1",
      "Value": "Value for Data Field 1"
    },
    {
      "Key": "DataField2",
      "Value": "Value for DataField2"
    }
  ]
}
  • Note: Spaces and special characters in Data Fields must be replaced by underscores in the "Key" names.
  • Note: "Key" names for Data Fields in single instance Data Sections must be entered using dot notation (e.g. "DataSectionName.DataFieldName")
  • This information is passed in the API call's header.

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 scenario 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

When Grooper processes the API request, it maps the data in "FieldValues" header to the corresponding Data Fields in the Data Model.


In this example, we used the following JSON to populate the Batch's "ID Number" and "Prepared By" fields. 

{
  "FieldValues": [
    {
      "Key": "ID_Number",
      "Value": "0002"
    },
    {
      "Key": "Prepared_By",
      "Value": "Guy Grooper"
    }
  ]
}

This is the result in the API tester.


Inspecting the Batch's data (at the Batch level), we can see the CreateBatch endpoint not only created the Batch, but it uploaded the data to each Data Field correctly.

Example response when Batch creation is successful: 

{
  "Id": "367ad5d4-bfdf-41fd-aed5-dbd9adcfc9d6",
  "Name": "Bovine Applications Batch 0002",
  "NodeIndex": 1,
  "NumChildren": 2,
  "ParentId": "3c354a8a-aa39-43d5-aeac-64e9f974c353",
  "TypeName": "Grooper.Core.Batch",
  "Created": "/Date(1713458435618-0500)/",
  "CreatedBy": "BIS\\dgreenwood",
  "Priority": 3,
  "RootFolderId": "f086aad2-f2c4-493f-b4d2-8c17b75eac8f",
  "Status": 4,
  "StepNo": 0
}

Error response when no Content Type is assigned to a Batch Process. 

{
  "Message": "Fields may only be specified when the process defines a content type."
}

Error response if no Data Field is found for a "Key" in the FieldValues JSON.

  • You will receive this error if the Data Field does not exist in the Data Model.
{
  "Message": "Field 'BadFieldName' not found."
}

CreateDocument: Create a Batch Folder with Attachment file

POST {baseUrl}/api/v1/BatchProcessing/Folders/{ParentId}/CreateDocument/{FileName}?MimeType={MimeType}

This request will create a new "document" in Grooper. More specifically, it will create a Batch Folder with a file attached to it. Practically speaking, this is how users import files into Grooper using the Grooper REST API.


The CreateDocument endpoint has three required parameters and one optional parameter.

  • Required Parameters
    • {ParentId}: You must enter the parent Batch Folder's ID (GUID).
      • This is the folder in the Batch you want to put the document.
      • When uploading to the root of a Batch this is not the Batch's ID. It is the Batch's root folder's ID.
    • "Stream": You must enter a file path for the file you want attached to the created Batch Folder.
      • This is the file you want to import and its location in a file system.
      • The API tester allows you to use a file browser to select a file stream.
      • This information is passed in the CreateDocument request's header.
    • {FileName}: You must enter a file name for the file.
  • Optional Parameters:
    • {MimeType}: You may optionally enter a MIME type for the attachment.
      • If you do not want to alter the source file's MIME type, you do not need to configure this parameter.
      • FYI: These are the most common MIME types.
        • jpg: image/jpeg
        • jpeg: image/jpeg
        • png: image/png
        • json: application/json
        • pdf: application/pdf
        • tif: image/tiff
        • tiff: image/tiff
        • txt: text/plain
        • xml: XML


In this example, we used CreateDocument to create a new Batch Folder with a PDF attachment. We did not change the MIME type in this example, as it was unnecessary. Practically speaking, this imported a new document into Grooper using the API.

  • FYI: We imported the original manual for the Pet Rock. You can find this on Archive.org here.



Success! A new Batch Folder was added to the folder we chose (the root of this Batch in this case) with the source file attached to it, now named "import_file_0001.pdf".


Example response:

  • A successful response is always the file's MIME type and file size.
Type: application/pdf, Size: 309

CreateFolder: Create an empty Batch Folder (optionally with Data Field values)

POST {baseUrl}/api/v1/BatchProcessing/Folders/{ParentId}/CreateFolder

This request creates a new empty folder. It adds an empty Batch Folder to a Batch's root folder or any other Batch Folder. Optionally, you can set the folder's Document Type and enter Data Field values using the "Metadata" parameter.


The CreateFolder endpoint has one required parameter and one optional parameter.

  • Required Parameters:
    • {ParentId}: You must enter the parent Batch Folder's ID (GUID).
      • This is the folder in the Batch you want to put the document.
      • When uploading to the root of a Batch this is not the Batch's ID. It is the Batch's root folder's ID.
  • Optional Parameters:
    • "Metadata": You may optionally enter metadata for the Batch Folder, setting the folder's Content Type (usually Document Type) and enter values for single instance Data Fields.
      • Content Type and Data Field values are edited with formatted JSON. See example below.
{
  "ContentTypeId": "00000000-0000-0000-0000-000000000000",
  "FieldValues": [
    {
      "Key": "Data_Field_1",
      "Value": "Value for Data Field 1"
    },
    {
      "Key": "DataField2",
      "Value": "Value for DataField2"
    }
  ]
}
  • Note: Spaces and special characters in Data Fields must be replaced by underscores in the "Key" names.
  • Note: "Key" names for Data Fields in single instance Data Sections must be entered using dot notation (e.g. "DataSectionName.DataFieldName")
  • This information is passed in the API call's header.


In this example, we will create a new Batch Folder (added to the root folder of a Batch). We will also assign this folder a Document Type and edit a single Data Field in its Data Model , using the following JSON. 

{
  "ContentTypeId": "57dd9e5b-1b56-4db7-8d47-dd641b33bd0b",
  "FieldValues": [
    {
      "Key": "Employee_ID",
      "Value": "KL51239"
    }
  ]
}



The API created the Batch Folder and edited the "Employee ID" Data Field with the value we provided.


Please Note: The Batch Folder does not have any document content. It is simply an empty Batch Folder at this point with whatever Data Field values we upload using the "Metadata" parameter. To add document content to this folder, we would need to use the CreatePage or SetAttachment endpoints.

Example JSON response: 

{
  "Id": "59addb8b-c266-4e7a-9282-7d544ba97bbe",
  "Name": "Info Sheet (1)",
  "NodeIndex": 0,
  "NumChildren": 0,
  "ParentId": "c4308600-4d35-426a-8614-9619fdb32589",
  "TypeName": "Grooper.Core.BatchFolder",
  "DataIsValid": true,
  "JsonData": "Grooper.DocumentData.json",
  "TypeId": "57dd9e5b-1b56-4db7-8d47-dd641b33bd0b",
  "XmlData": "Grooper.DocumentData.xml"
}

CreatePage: Add Batch Pages to a Batch Folder

POST {baseUrl}/api/v1/BatchProcessing/Folders/{ParentId}/CreatePage

This request creates a new page. It adds a Batch Page to a Batch Folder.


The CreatePage endpoint has two required parameters.

  • Required Parameters:
    • {ParentId}: You must enter the parent Batch Folder's ID (GUID).
      • This is the folder in the Batch you want to put the page.
      • When uploading to the root of a Batch this is not the Batch's ID. It is the Batch's root folder's ID.
    • "Stream": You must enter a file path for the page you want to add.
      • The API tester allows you to use a file browser to select a file stream.
      • This information is passed in the API call's header.

PLEASE NOTE: The file content must be a single-paged PDF or image-based file format.


In this example, we add a JPG page to a folder in a Batch.



Success! The page has been added to the folder.


Example JSON response:

  • A successful response will always be the page's MIME type and file size.
Type: image/jpeg, Size: 322

SetAttachment: Attach a file to a Batch Folder

POST {baseUrl}/api/v1/BatchProcessing/Folders/{FolderId}/{FileName}?MimeType={MimeType}

This request will attach a file to an existing Batch Folder. SetAttachment is similar to CreateDocument. The only difference is SetAttachment simply attaches the file to an existing folder, where CreateDocument both creates the folder and attaches the file to it.


The SetAttachment endpoint has three required parameters and one optional parameter.

  • Required Parameters:
    • {FolderId}: You must enter the Batch Folder's ID (GUID).
      • This is the folder you want to attach the file to.
    • "Stream": You must enter a file path for the file you want attach.
      • This is the file you want to import and its location in a file system.
      • The API tester allows you to use a file browser to select a file stream.
      • This information is passed in the CreateDocument request's header.
    • {FileName}: You must enter a file name for the file.
  • Optional Parameters:
    • {MimeType}: You may optionally enter a MIME type for the attachment.
      • If you do not want to alter the source file's MIME type, you do not need to configure this parameter.
      • FYI: These are the most common MIME types.
        • jpg: image/jpeg
        • jpeg: image/jpeg
        • png: image/png
        • json: application/json
        • pdf: application/pdf
        • tif: image/tiff
        • tiff: image/tiff
        • txt: text/plain
        • xml: XML


In this example, we will attach a CSV file to an existing folder in a Batch.



Success! The CSV file was attached to the Batch Folder, now named "attached_file_0001.csv".


Example response:

  • A successful response is always the file's MIME type and file size.
Type: text/csv, Size: 4

SetMetadata: Edit a document's Data Field values

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

This request will set a folder's Document Type and edit its Data Field values. SetMetadata is similar to CreateFolder. The only difference is SetMetadata only edits the folder's "metadata" (Document Type and Data Field values) for an existing folder, where CreateFolder both creates the folder and can edit its metadata.


The SetMetadata endpoint has two required parameters.

  • Required Parameters:
    • {FolderId}: You must enter the Batch Folder's ID (GUID).
      • This is the document whose data you want to edit.
    • "Metadata": Use this parameter to set the folder's Content Type (usually Document Type) and enter values for single instance Data Fields.
      • Content Type and Data Field values are edited with formatted JSON. See example below.
{
  "ContentTypeId": "00000000-0000-0000-0000-000000000000",
  "FieldValues": [
    {
      "Key": "Data_Field_1",
      "Value": "Value for Data Field 1"
    },
    {
      "Key": "DataField2",
      "Value": "Value for DataField2"
    }
  ]
}
  • Note: Spaces and special characters in Data Fields must be replaced by underscores in the "Key" names.
  • Note: "Key" names for Data Fields in single instance Data Sections must be entered using dot notation (e.g. "DataSectionName.DataFieldName")
  • This information is passed in the API call's header.


In this example, we assign an existing folder's Document Type and edit a single Data Field in its Data Model , using the following JSON. 

{
  "ContentTypeId": "57dd9e5b-1b56-4db7-8d47-dd641b33bd0b",
  "FieldValues": [
    {
      "Key": "Employee_ID",
      "Value": "KL51239"
    }
  ]
}



The API assigned the document the "Info Sheet" Document Type and edited the "Employee ID" Data Field with the value we provided.


When SetMetadata successfully alters a Batch Folder's metadata the server response is simply true

Retrieved from "https://wiki.grooper.com/index.php?title=2023.1:API_Services_(Service)&oldid=22608"