View source for 2023.1:API Services (Service)

{{AutoVersion}}

<blockquote>{{#lst:Glossary|API Services}}</blockquote>

{|class="download-box"
|
[[File:Asset 22@4x.png]]
|
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.
* [[Media:2023.1_API-Services_Batches.zip]]
* [[Media:2023.1_API-Services_Project.zip]]

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

== 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'''''.

{|class="attn-box"
|
&#9888;
|
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: <code>apikey</code>
* value format (GUID): <code>00000000-0000-0000-0000-000000000000</code>

Instructions on how to obtain an API key are found in the [[2023:API Services#Install the Grooper API Services|How to install the Grooper API Services]] tutorial.
|}

== How To: Install the Grooper API Services ==

{|class="attn-box"
|
&#9888;
|
The Grooper Service User must have the "Logon as Service" permission."
|}

# In Grooper config click the "Edit Services" button to open the "Service Manager" window.
[[File:2023 APIServices 02HowTo 01.png]]


# <li value=2>From the Service Manager window click the "Install" button.</li>
# Select the desired repository from the "Repository" dropdown.
# Choose API Services.
# Click the "OK" button to confirm and open the "API Services" window.
[[File:2023 APIServices 02HowTo 02.png]]


# <li value=6>From the "API Services" window add an API key for the '''''API Keys''''' property.</li>
# Copy the API endpoint URL from the '''''URL''''' property.
# Ensure the Windows service user credentials are correct on the '''''User Name''''' and '''''Password''''' properties.
# When finished configuring click the "Execute" button to confirm changes and close the "API Services" window.
[[File:2023 APIServices 02HowTo 03.png]]


# <li value=10>In the "Service Manager" window, with the newly created "Grooper API Services" service installed and selected, click the "Start" button.</li>
#* '''FYI''' - If everything was configured properly, the "Status" of the service will change from "Stopped" to "Running".
[[File:2023 APIServices 02HowTo 04.png]]

== 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.
<br><br>
# When editing an "API Services" service, in the "API Services" window, set the '''''Enable Test Endpoint''''' property to ''True''.
# Copy the API endpoint URL from the '''''URL''''' property.
# When finished configuring click the "Execute" button to confirm changes and close the "API Services" window.
[[File:2023 APIServices 02HowTo 05.png]]
<br><br>
# <li value=4> Paste the copied URL into a browser of your choice.</li>
[[File:2023 APIServices 02HowTo 06.png]]
<br><br>
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 <code>{BatchID}</code> with the a '''Batch's''' ID (GUID).

{|class="attn-box"
|
&#9888;
|
'''''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 ====

<code>DELETE {baseUrl}/api/v1/BatchProcessing/Batches/{BatchId}</code>

This request will delete a '''Batch''' in Grooper.  


The DeleteBatch endpoint has one required parameter.
* Required Parameters
** <code>{BatchId}</code>: Enter the ID (GUID) for the '''Batch''' you want to delete.


If successfully deleted, the response will be <code>true</code>

[[File:2023 APIServices 03 01 01 DeleteBatch.png|center|class=simpleborder]]

==== GetBatchInfo: Get info for a specific Batch ====

<code>GET {baseUrl}/api/v1/BatchProcessing/Batches/{BatchId}</code>

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
** <code>{BatchId}</code>:  Enter the '''Batch's''' ID (GUID) to return information about it.


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

[[File:2023 APIServices 03 01 02 GetBatchInfo.png|class=simpleborder|center]]

See below for an example response:

<pre>
{
  "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
}
</pre>

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

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

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:
** <code>{Level}</code>:  Enter an integer for the level of the '''Batches > Production''' folder you want to query.
*** Entering <code>Level=0</code> 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 <code>0</code> for the <code>{Level}</code>.  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.

[[File:2023 APIServices 03 01 02 GetBatchInfos-01.png|class=simpleborder|center]]


Entering a <code>{Level}</code> other than <code>0</code> 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 <code>{Level}</code> to <code>2</code>, returning information about the single '''Batch''' at the second level of the Production branch.

[[File:2023 APIServices 03 01 02 GetBatchInfos-02.png|class=simpleborder|center]]

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

<code>GET {baseUrl}/api/v1/BatchProcessing/Files/{ItemId}/{FileName}</code>

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
** <code>{ItemId}</code>:  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
** <code>{FileName}</code>:  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, <code>{ItemId}</code> was set to the GUID of a '''Batch Folder''' and <code>{FileName}</code> was set to the name of an attached PDF.
* The MIME type and file size for that file was returned.

[[File:2023 APIServices 03 01 04 GetContentStream.png|class=simpleborder|center]]


See below for an example response for a pdf file:

<pre>
Type: application/pdf, Size: 75922
</pre>


See below for an example response of a "Grooper.DocumentData.json" file:
<tab name="Click here to expand/collapse the example" collapsed>
<pre>
{
  "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
}
</pre>
</tab>

==== GetContentTypes: Get info for all Content Types ====

<code>GET {baseUrl}/api/v1/BatchProcessing/ContentTypes</code>

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.

[[File:2023 APIServices 03 01 05 GetContentTypes.png|class=simpleborder|center]]

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"): 

<pre>
[
  {
    "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"
      }
    ]
  }
]
</pre>

==== GetFolderInfo: Get info for a single Batch Folder ====

<code>GET {baseUrl}/api/v1/BatchProcessing/Folders/{FolderId}</code>

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
** <code>{FolderId}</code>:  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.
[[File:2023 APIServices 03 01 06 GetFolderInfo.png|class=simpleborder|center]]


Example JSON response if the '''Batch Folder''' exists:

<pre>
{
  "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"
}
</pre>


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

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


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

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

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

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

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
** <code>{ParentId}</code>: Enter the parent folder's ID (GUID) for any parent folder you want to search in.
** <code>{Level}</code>: 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, <code>{ParentId}</code> was set to the GUID for a '''Batch's''' root folder, and we entered <code>1</code> for the <code>Level</code>.
* There were three total '''Batch Folders''' at that level.  
* Information for all three was returned in the JSON response.

[[File:2023 APIServices 03 01 07 GetFolders.png|class=simpleborder|center]]

See below for an example JSON response:
<tab name="Click here to expand/collapse the example" collapsed>
<pre>
[
  {
    "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
  }
]
</pre>
</tab>

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

<code>GET {baseUrl}/api/v1/BatchProcessing/Folders/{FolderId}/Metadata</code>

This request returns data Grooper extracted for a document ('''Batch Folder''').  

Two things are returned:
# A "ContentTypeId" value for the document (This is its '''Document Type's''' GUID).
# 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:
 <pre style="margin-left:68px">
"FieldValues": [
  {
    "Key": "Social_Sec_Num",
    "Value": "000-00-0000"
  }
]
</pre>
:::* 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. <code>"DataSectionName.DataFieldName"</code>)


The GetMetadata endpoint has one required parameter.
*Required Parameters:
** <code>{FolderId}</code>: 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'''.

[[File:2023 APIServices 03 01 08 GetMetadata.png|class=simpleborder|center]]

See below for an example response:

<pre>
{
  "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"
    }
  ]
}
</pre>

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

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

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
** <code>{ParentId}</code>: Enter the ID (GUID) for the '''Batch Folder''' containing the pages.
** <code>{Recursive}</code>: Enter <code>True</code> or <code>False</code> to indicate if the search is recursive.
*** <code>True</code> if you want all pages from all levels below the '''Batch Folder'''
*** <code>False</code> if you want ''only'' pages at the given '''Batch Folder''' level.


Example when <code>Recursive=False</code>:
*Here, there was only a single page at the selected '''Batch Folder's''' level.

[[File:2023 APIServices 03 01 09 GetPages-01.png|class=simpleborder|center]]


Example JSON response when <code>Recursive=False</code>:

<pre>
[
  {
    "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
  }
]
</pre>


Example when <code>Recursive=True</code>:
* Here, there are two pages.  One is at level 1 and the other at level 2.

[[File:2023 APIServices 03 01 09 GetPages-02.png|class=simpleborder|center]]


Example JSON response when <code>Recursive=True</code>:
<pre>
[
  {
    "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
  }
]
</pre>

==== GetProcess: Get information about a published Batch Process ====

<code>GET {baseUrl}/api/v1/BatchProcessing/Process?Process={Process}</code>

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:
** <code>{Process}</code>:  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.


{|style="text-align:center" cellpadding=4
|valign=top|
Example when entering the published '''Batch Process's''' name.
|valign=top|
Example when entering the working '''Batch Process's''' GUID.
|-
|valign=top|
[[File:2023 APIServices 03 01 10 GetProcess-01.png|class=simpleborder|center]]
|valign=top|
[[File:2023 APIServices 03 01 10 GetProcess-02.png|class=simpleborder|center]]
|-
|colspan=2|
''Notice the API response results are the same.''
|}

Example JSON Response:
<tab name="Click here to expand/collapse the example" collapsed>
<pre>
{
  "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
    }
  ]
}
</pre>
</tab>


Error response when an invalid '''Batch Process''' name is passed:
* You will get this error if no ''published'' '''Batch Process''' with that name exists.

<pre>
{
  "Message": "Invalid Published Process Name."
}
</pre>


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.

<pre>
{
  "Message": "Invalid Working Process Id."
}
</pre>

==== GetProcesses: Get a list of all published Batch Processes ====

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

This returns a list of all published '''Batch Processes'''.  


The GetProcesses endpoint has one required parameter.
* Required Parameters
** <code>{Verbose}</code>: You must enter <code>True</code> or <code>False</code> for this parameter.
*** <code>Verbose=False</code> will return a simple list of published '''Batch Processes''' and some information about them (Their "Id", "Name", "ParentId" and more).
*** <code>Verbose=True</code> will return a nested list of published '''Batch Processes''' ''and'' information about about each of their steps.


{|cellpadding=4
|valign=top|
Example when using <code>Verbose=False</code>
* In this example, only two '''Batch Processes''' in the repo are published.
* The API returns ''just'' information about the '''Batch Processes''' ''not'' their steps.
|valign=top|
Example when using <code>Verbose=True</code>
* In this example, only two '''Batch Processes''' in the repo are published.
* The API returns information about the '''Batch Processes''' ''and'' their steps.
|-
|valign=top style="width:50%"|
[[File:2023 APIServices 03 01 11 GetProcesses-01.png|class=simpleborder|center]]
|valign=top|
[[File:2023 APIServices 03 01 11 GetProcesses-02.png|class=simpleborder|center]]
|}

Example JSON response when <code>{Verbose}</code> is <code>False</code>
<tab name="Click here to expand/collapse the example" collapsed>
</pre>
[
  {
    "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
  }
]
</pre>
</tab>


Example JSON response when <code>{Verbose}</code> is <code>True</code>
<tab name="Click here to expand/collapse the example" collapsed>
</pre>
[
  {
    "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
      }
    ]
  }
]
</pre>
</tab>

==== PauseBatch: Pause a Batch ====

<code>GET {baseUrl}/api/v1/BatchProcessing/Batches/{BatchId}/Pause</code>

This request will pause a '''Batch''' in production.  


The PauseBatch endpoint has one required parameter.
* Required Parameters
** <code>{BatchId}</code>:  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".

[[File:2023 APIServices 03 01 12 PauseBatch-01.png|class=simpleborder|center]]


See below for an example response:
<pre>
{
  "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
}
</pre>

==== StartBatch: Start/resume processing on a Batch ====

<code>GET {baseUrl}/api/v1/BatchProcessing/Batches/{BatchId}/Start</code>

This request will start processing a '''Batch''' (or otherwise resume processing for a paused '''Batch''').  


The StartBatch endpoint has one required parameter.
* Required Parameters
** <code>{BatchId}</code>:  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".

[[File:2023 APIServices 03 01 13 StartBatch-01.png|class=simpleborder|center]]


See below for an example response:

<pre>
{
  "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
}
</pre>

==== CreateBatch: Create a new Batch ====

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

This request will create a new '''Batch''' in Grooper. 


This CreateBatch endpoint has one required parameter and two optional parameters.  
* Required Parameters
** <code>{ProcessName}</code>: 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
** <code>{BatchName}</code>:  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.
<pre style="margin-left:68px">
{
  "FieldValues": [
    {
      "Key": "Data_Field_1",
      "Value": "Value for Data Field 1"
    },
    {
      "Key": "DataField2",
      "Value": "Value for DataField2"
    }
  ]
}
</pre>
:::* 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. <code>"DataSectionName.DataFieldName"</code>)
::* 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 <code>{ProcessName}</code> parameter, enter the name of the '''Batch Process''' you wish to execute. Be sure to use the ''published'' version's name.
* Using the <code>{BatchName}</code> parameter, enter a name for the '''Batch'''.

[[File:2023 APIServices 03 01 14 CreateBatch-01.png|class=simpleborder|center]]

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

{|style="margin:auto; max-width:75%"
|valign=top style="width:50%"|
In our example, our process's '''''Content Type''''' property references "Cow Apps".

[[File:2023 APIServices 03 01 14 CreateBatch-02.png|class=simpleborder|center]]
|valign=top style="padding-left:20px"|
"Cow Apps" is a '''Content Model'''.  Its '''Data Model''' has two '''Data Fields''':  
:* "ID Number"
:* "Prepared By"

[[File:2023 APIServices 03 01 14 CreateBatch-03.png|class=simpleborder|center]]

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.
<pre>
{
  "FieldValues": [
    {
      "Key": "ID_Number",
      "Value": "0002"
    },
    {
      "Key": "Prepared_By",
      "Value": "Guy Grooper"
    }
  ]
} 
</pre>

This is the result in the API tester.
[[File:2023 APIServices 03 01 14 CreateBatch-04.png|class=simpleborder|center]]


[[File:2023 APIServices 03 01 14 CreateBatch-05.png|class=simpleborder|left]]
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.
<br clear=all>

Example response when '''Batch''' creation is successful:
<pre>
{
  "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
}
</pre>

Error response when no '''Content Type''' is assigned to a '''Batch Process'''.
<pre>
{
  "Message": "Fields may only be specified when the process defines a content type."
}
</pre>

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'''.
<pre>
{
  "Message": "Field 'BadFieldName' not found."
}
</pre>

==== CreateDocument: Create a Batch Folder with Attachment file ====
<code>POST {baseUrl}/api/v1/BatchProcessing/Folders/{ParentId}/CreateDocument/{FileName}?MimeType={MimeType}</code>

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
** <code>{ParentId}</code>: 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.
** <code>{FileName}</code>: You ''must'' enter a file name for the file.
* Optional Parameters:
** <code>{MimeType}</code>: 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 [https://archive.org/details/pet_rock_manual_original here].

[[File:2023 APIServices 03 01 15 CreateDocument-05.png|class=simpleborder|center]]


[[File:2023 APIServices 03 01 15 CreateDocument-02.png|class=simpleborder|left|800px]]


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".
<br clear=all>


Example response: 
* A successful response is always the file's MIME type and file size.
<pre>
Type: application/pdf, Size: 309
</pre>

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

<code>POST {baseUrl}/api/v1/BatchProcessing/Folders/{ParentId}/CreateFolder</code>

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:
** <code>{ParentId}</code>: 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.
<pre style="margin-left:60px">
{
  "ContentTypeId": "00000000-0000-0000-0000-000000000000",
  "FieldValues": [
    {
      "Key": "Data_Field_1",
      "Value": "Value for Data Field 1"
    },
    {
      "Key": "DataField2",
      "Value": "Value for DataField2"
    }
  ]
}
</pre>
:::* 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.
<pre>
{
  "ContentTypeId": "57dd9e5b-1b56-4db7-8d47-dd641b33bd0b",
  "FieldValues": [
    {
      "Key": "Employee_ID",
      "Value": "KL51239"
    }
  ]
}
</pre>

[[File:2023 APIServices 03 01 16 CreateFolder-01.png|class=simpleborder|center]]


[[File:2023 APIServices 03 01 16 CreateFolder-02.png|class=simpleborder|right]]


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.
<br clear=all>

Example JSON response:
<pre>
{
  "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"
}
</pre>

==== CreatePage: Add Batch Pages to a Batch Folder ====

<code>POST {baseUrl}/api/v1/BatchProcessing/Folders/{ParentId}/CreatePage</code>

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


The CreatePage endpoint has two required parameters.
* Required Parameters:
** <code>{ParentId}</code>: 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'''.

[[File:2023 APIServices 03 01 17 CreatePage-01.png|class=simpleborder|center]]



[[File:2023 APIServices 03 01 17 CreatePage-02.png|class=simpleborder|left]]


Success!  The page has been added to the folder.

<br clear=all>

Example JSON response:
* A successful response will always be the page's MIME type and file size.
<pre>
Type: image/jpeg, Size: 322
</pre>

==== SetAttachment: Attach a file to a Batch Folder ====

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

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:
** <code>{FolderId}</code>: 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.
** <code>{FileName}</code>: You ''must'' enter a file name for the file.
* Optional Parameters:
** <code>{MimeType}</code>: 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'''.

[[File:2023 APIServices 03 01 18 SetAttachment-01.png|class=simpleborder|center]]


[[File:2023 APIServices 03 01 18 SetAttachment-02.png|class=simpleborder|left]]


Success! The CSV file was attached to the '''Batch Folder''', now named "attached_file_0001.csv".
<br clear=all>


Example response:
* A successful response is always the file's MIME type and file size.
<pre>
Type: text/csv, Size: 4
</pre>

==== SetMetadata: Edit a document's Data Field values ====

<code>POST {baseUrl}/api/v1/BatchProcessing/Folders/{FolderId}/Metadata</code>

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:
** <code>{FolderId}</code>: 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.
<pre style="margin-left:60px">
{
  "ContentTypeId": "00000000-0000-0000-0000-000000000000",
  "FieldValues": [
    {
      "Key": "Data_Field_1",
      "Value": "Value for Data Field 1"
    },
    {
      "Key": "DataField2",
      "Value": "Value for DataField2"
    }
  ]
}
</pre>
:::* 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.
<pre>
{
  "ContentTypeId": "57dd9e5b-1b56-4db7-8d47-dd641b33bd0b",
  "FieldValues": [
    {
      "Key": "Employee_ID",
      "Value": "KL51239"
    }
  ]
}
</pre>

[[File:2023 APIServices 03 01 19 SetMetadata-01.png|class=simpleborder|center]]


[[File:2023 APIServices 03 01 16 CreateFolder-02.png|class=simpleborder|right]]


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 <code>true</code>
<br clear=all>

== Glossary ==
<u>'''API Services'''</u>: {{#lst:Glossary|API Services}}

<u>'''Activity'''</u>: {{#lst:Glossary|Activity}}

<u>'''Batch Folder'''</u>: {{#lst:Glossary|Batch Folder}}

<u>'''Batch Page'''</u>: {{#lst:Glossary|Batch Page}}

<u>'''Batch Process'''</u>: {{#lst:Glossary|Batch Process}}

<u>'''Batch'''</u>: {{#lst:Glossary|Batch}}

<u>'''Classify'''</u>: {{#lst:Glossary|Classify}}

<u>'''Content Model'''</u>: {{#lst:Glossary|Content Model}}

<u>'''Content Type'''</u>: {{#lst:Glossary|Content Type}}

<u>'''Data Element'''</u>: {{#lst:Glossary|Data Element}}

<u>'''Data Field'''</u>: {{#lst:Glossary|Data Field}}

<u>'''Data Model'''</u>: {{#lst:Glossary|Data Model}}

<u>'''Data Section'''</u>: {{#lst:Glossary|Data Section}}

<u>'''Document Type'''</u>: {{#lst:Glossary|Document Type}}

<u>'''Execute'''</u>: {{#lst:Glossary|Execute}}

<u>'''Export'''</u>: {{#lst:Glossary|Export}}

<u>'''Extract'''</u>: {{#lst:Glossary|Extract}}

<u>'''File Store'''</u>: {{#lst:Glossary|File Store}}

<u>'''Grooper Repository'''</u>: {{#lst:Glossary|Grooper Repository}}

<u>'''Grooper Service'''</u>: {{#lst:Glossary|Grooper Service}}

<u>'''Image Processing'''</u>: {{#lst:Glossary|Image Processing}}

<u>'''Image Processing'''</u>: {{#lst:Glossary|Image Processing}}

<u>'''Project'''</u>: {{#lst:Glossary|Project}}

<u>'''Recognize'''</u>: {{#lst:Glossary|Recognize}}

<u>'''Repository'''</u>: {{#lst:Glossary|Repository}}

<u>'''Review'''</u>: {{#lst:Glossary|Review}}

<u>'''Root'''</u>: {{#lst:Glossary|Root}}

<u>'''Scope'''</u>: {{#lst:Glossary|Scope}}

<u>'''Service'''</u>: {{#lst:Glossary|Service}}

<u>'''Split Pages'''</u>: {{#lst:Glossary|Split Pages}}

<u>'''Split'''</u>: {{#lst:Glossary|Split}}

<u>'''Thread'''</u>: {{#lst:Glossary|Thread}}