Skip to main content
Skip table of contents

GlobalSearch Postman Collection

Please note that any requests for deleting GlobalSearch Objects (like database, archives, fields, lists, tables, documents, etc) will happen instantly and cannot be reversed. Use with care and consideration.

Initial Configuration

Download and import postman collection below;

GlobalSearch Collection.postman_collection_v0.4.json
Create a Postman Environment with the following values;

  • user - Windows or Square 9 username. If a windows domain user include the domain prefix

  • password - Password for the user, should be set to be type "secret"

  • domain - the FQDN of the GlobalSearch server, including the HTTP/HTTPS protocol

Using different environments in this manner allows you to quickly switch between users and GlobalSearch Servers. Note that you may have clear Postman cookies!

Minimum environment variables that have to be configured for use with the collection

If you are having issues with tokens/authentication after changing environments it is likely because there is still a license token stored in the Postman cookies, see the section below for details on how to address this issue.

Enabling Postman cookie access

The Authentication and Licensing/Get License request will store the returned license token both as a cookie and as a Postman collection variable. The cookies are carried over to other requests made from the same collection and used for authentication. The Get License request is configured to clear out the cookies prior to running so that the returned values are stored correctly. For this to work you have to first enable access to the domain that the requests are going to;

  • From any request select the “Cookies” link underneath the Send button in Postman

  • Click the “Domains Allowlist” at the bottom of the popup window and add the domain of your GlobalSearch server as appropriate

Getting a License

See Authentication and Licensing/Get License
GET request to /square9api/api/licenses, uses Basic Authentication to pass in user name and password.

The username and password are populated by the Postman Environment ({{user}} and {{password}} variables) currently in use.

The response to this request will contain the token in both the request body, cookies and headers. Both a authenticatedUser and sstoken cookie are created. The Postman application is pretty good at handling these and carrying them over to other requests, if you are creating a standalone application you will either need to add these cookies or always pass in the token via URL parameter.

Deleting a License

See Authentication and Licensing/Delete License

DEL request to /square9api/api/licenses/{token} will delete (pre GlobalSearch 6.1) or deactivate (GlobalSearch 6.1+) the given license token.

Managing Licenses is an important part of interacting with GlobalSearch APIs, you should attempt to use licenses for as small a time as possible and return (or delete) them when not in use so that human users of GlobalSearch have enough licenses available to access the program.

DatabaseIDs

See Database/Get Database List

Each GlobalSearch Database will have a unique database ID, these are static values and will not change under normal circumstances

Example Response Body

The response will be a JSON document with a list of the databases in the GlobalSearch Instance. Each item in the databases list will have an “Id” key/value pair, this represents the Database ID for the Database.

Get Database List example response body
CODE
{
    "Databases": [
        {
            "Id": 1,
            "Name": "SmartSearch",
            "SecurityLevel": 0,
            "Manager": null
        },
        {
            "Id": 2,
            "Name": "BrewHaven",
            "SecurityLevel": 0,
            "Manager": null
        }
    ]
}

From the above we can see that the “SmartSearch” database has a database ID of 1 while the “BrewHaven” database has a database ID of 2.

ArchiveIDs

See Archives\Get Archives

Each GlobalSearch Archive will have a static and unique archive ID that is used to identify the Archive.

Example Response Body

The response body will be a JSON array with each object representing one archive. The “ID” key/value pair will be the ArchiveID that is used in other Square9API requests

Get Archives example response body
CODE
[
    {
        "ID": 1,
        "Name": "LEGAL",
        "Parent": 0,
        "BasePath": {
            "Default": false,
            "Path": "C:\\GlobalSearch\\archive\\SmartSearch\\TestArchiv",
            "UniqueName": false
        },
        "CreateBrowse": false,
        "Fields": [
            19,
            20
        ],
        "Views": {
            "Enabled": false,
            "StatusField": 0,
            "Values": []
        },
        "ContentSearch": true,
        "RevisionControl": 0,
        "ConvertPdf": true,
        "Notifications": {
            "To": "",
            "From": "",
            "Subject": "",
            "Message": ""
        }
    },
    {
        "ID": 1003,
        "Name": "DataXChange Test",
        "Parent": 0,
        "BasePath": {
            "Default": true,
            "Path": "C:\\GlobalSearch\\archive\\SmartSearch\\DataXChange Test",
            "UniqueName": false
        },
        "CreateBrowse": false,
        "Fields": [
            5054,
            2028,
            2029,
            2030,
            2031,
            2032,
            1023
        ],
        "Views": {
            "Enabled": false,
            "StatusField": 0,
            "Values": []
        },
        "ContentSearch": false,
        "RevisionControl": 0,
        "ConvertPdf": false,
        "Notifications": {
            "To": "",
            "From": "",
            "Subject": "",
            "Message": ""
        }
    },
    {
        "ID": 5036,
        "Name": "DataDocsTest",
        "Parent": 0,
        "BasePath": {
            "Default": true,
            "Path": "C:\\GlobalSearch\\archive\\SmartSearch\\DataDocsTest",
            "UniqueName": false
        },
        "CreateBrowse": false,
        "Fields": [],
        "Views": {
            "Enabled": false,
            "StatusField": 0,
            "Values": []
        },
        "ContentSearch": false,
        "RevisionControl": 0,
        "ConvertPdf": false,
        "Notifications": {
            "To": "",
            "From": "",
            "Subject": "",
            "Message": ""
        }
    }
]

In the above example response we can see that the “LEGAL” archive has an ID of “1”.

SecureIDs

Please note that you should always fetch the SecureID values anytime that you need to use them, they are updated often. This applies to any version of the SecureID, whether it be search or document.

SecureIDs are hashes used to uniquely identify a Search or a Document.

Document SecureID

See Document Actions/Get Document Secure ID

You will need to pass in the Database ID, ArchiveID and DocumentID as well as a license token.

Response:

The response if successful will simply be the document’s SecureID.

CODE
c8e570f5c59ba9e5fe0d33fc8b02906e795b27b126355bd84d6a3c3afdab647c

Search SecureID

See Searching/Get Archive Searches or Searching/Get Archive Search if you know the SearchID already

Generally any request that returns information about a search should include the Search’s SecureID. See below for an example response from Get Archive Search where we are passing in the search id via URL parameter.

Response:

The response will be a JSON document describing information about the Search, included will be the “Hash” key/value pair, this is the Search SecureID.

Get Archive Search example response body
CODE
[
    {
        "Archives": [
            {
                "ID": 1,
                "Name": "LEGAL"
            }
        ],
        "Id": 1,
        "Parent": 1,
        "Name": "Browse TestArchiv123",
        "Hash": "d51d69e6892f6bde8b703e946e01c8ca6061e8dc29eb90f03b650dd38add64b6",
        "Detail": [
            {
                "ID": 8035,
                "FID": 19,
                "ListID": 9,
                "ListF1": 0,
                "ListF2": 0,
                "Parent": 0,
                "Operator": 6,
                "Prompt": "",
                "VAL": "ssIsNull",
                "Prop": 64,
                "FieldType": 1,
                "Mask": ""
            }
        ],
        "Props": 0,
        "Fuzzy": 0,
        "Grouping": "",
        "Settings": 6
    }
]

Here the “Hash” key/value pair will be the search SecureID.

FieldIDs

See Field Catalog/Fields/Get Fields or Searching/Get Archive Fields

Each GlobalSearch Field will have a unique field ID, you can retrieve this information in a number of ways. If you have access to the GlobalSearch web administration interface you can quickly check the FieldID by clicking on the “Three Dots” option on the field in question.

Food Sub type has a FieldID of 3

To retrieve FieldID information from the API you will have to run one of the requests previously mentioned.

Get Fields

This request will return all of the fields on the GlobalSearch Database. The FieldID is represented by the “ID” key/value pair for each entry in the response body.

Example Response Body

Get Fields example response body
CODE
[
    {
        "ID": 1,
        "Name": "Restaurant Name",
        "Type": "Character",
        "Format"Return: "",
        "Regex": "",
        "Length": 50,
        "Required": true,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": null,
            "ListId": 0,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 2,
        "Name": "Food Type",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": "dropdown",
            "ListId": 1,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 3,
        "Name": "Food Sub type",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": "dropdown",
            "ListId": 0,
            "Primary": 2,
            "Secondary": 0,
            "Mapping": [
                {
                    "PrimaryValue": "Ameican",
                    "SecondaryValue": "",
                    "ListId": 2
                },
                {
                    "PrimaryValue": "Asian",
                    "SecondaryValue": "",
                    "ListId": 3
                },
                {
                    "PrimaryValue": "European",
                    "SecondaryValue": "",
                    "ListId": 4
                }
            ]
        }
    },
    {
        "ID": 4,
        "Name": "Spiciness",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": "dropdown",
            "ListId": 0,
            "Primary": 2,
            "Secondary": 3,
            "Mapping": [
                {
                    "PrimaryValue": "Ameican",
                    "SecondaryValue": "BBQ",
                    "ListId": 5
                },
                {
                    "PrimaryValue": "Asian",
                    "SecondaryValue": "Thai",
                    "ListId": 5
                },
                {
                    "PrimaryValue": "European",
                    "SecondaryValue": "Italian",
                    "ListId": 5
                }
            ]
        }
    },
    {
        "ID": 5,
        "Name": "Restaurant Services",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": true,
        "SystemField": "",
        "List": {
            "Type": "dropdown",
            "ListId": 6,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 6,
        "Name": "Average Price",
        "Type": "Decimal",
        "Format": "c",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": null,
            "ListId": 0,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 7,
        "Name": "Miles From Home Office",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": "dropdown",
            "ListId": 7,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 8,
        "Name": "Rate The Food",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": "dropdown",
            "ListId": 8,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 9,
        "Name": "Rate The Service",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": "dropdown",
            "ListId": 8,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 10,
        "Name": "Rating Date",
        "Type": "Date",
        "Format": "d",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": null,
            "ListId": 0,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 11,
        "Name": "Rated By",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "",
        "List": {
            "Type": null,
            "ListId": 0,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 12,
        "Name": "Indexed By",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "indexedBy",
        "List": {
            "Type": null,
            "ListId": 0,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 13,
        "Name": "Date Indexed",
        "Type": "Date",
        "Format": "d",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "dateEntered",
        "List": {
            "Type": null,
            "ListId": 0,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 14,
        "Name": "Last Modified By",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "lastModified",
        "List": {
            "Type": null,
            "ListId": 0,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 15,
        "Name": "Date Last Modified",
        "Type": "Date",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "lastModified",
        "List": {
            "Type": null,
            "ListId": 0,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    },
    {
        "ID": 16,
        "Name": "File Type",
        "Type": "Character",
        "Format": "",
        "Regex": "",
        "Length": 50,
        "Required": false,
        "MultiValue": false,
        "SystemField": "fileType",
        "List": {
            "Type": null,
            "ListId": 0,
            "Primary": 0,
            "Secondary": 0,
            "Mapping": []
        }
    }
]

At this point, Get Archive Fields is worth mentioning as unlike the Get Fields request it will limit the returned information to be the fields on the archive in question.

Get Archive Fields

Returns a list of fields tied to the Archive passed in via URL

Example Response Body

Get Archive Fields example return body
CODE
[
    {
        "ID": 19,
        "Name": "Company",
        "List": 9,
        "Type": 1,
        "Mask": "",
        "Size": 50,
        "RegEx": "",
        "Prop": 64,
        "Parent": 0,
        "ListF1": 0,
        "ListF2": 0
    },
    {
        "ID": 20,
        "Name": "Provider",
        "List": 0,
        "Type": 1,
        "Mask": "",
        "Size": 50,
        "RegEx": "",
        "Prop": 192,
        "Parent": 0,
        "ListF1": 19,
        "ListF2": 0
    }
]

Uploading and Indexing a Document (in Chunks)

See Postman flow pictured below (while great for visualization of the process there is not a way to export/share flows from Postman at this time.)

Any variable used by a request in a flow if not retrieved from the flow itself is pulled from the Postman GlobalSearch Collection variables

Steps:

Get GlobalSearch License

  • Request: GET Authentication and Licenses/Get License

    • Uses Basic Authentication using the postman {{user}} and {{password}} variables (pulled from Postman Environment)

Start file upload to server

  • Request: POST Chunking Upload/Create Archive Job

    • this will return the unique JobID that you will need to use in later requests

    • The timestamp value here needs to be unique for each job

Upload file chunk

  • Request: POST Chunking Upload/Upload File Chunk
    Body:

    JSON
    {"Index":1, "RawData":base64endcodedfilecontent, "JobID":jobid}
    • In this example we are assuming that the file is small enough to be reasonably uploaded in one chunk.

    • PDF is base64 encoded, in this case since there is only one chunk the Index value is 1

      • Online Base64 encoding service: https://www.base64encode.org/

      • The Postman collection includes the {{pdfvaluefull}} variable which is a full PDF encoded to base64 that can be used with this request as long as you are doing a one chunk only upload.

If you wanted to upload in more than one chunk repeat this request (Upload File Chunk) with the next sequential chunk, being sure to increment the “Index” value in the Body of the request. Keeping the index values in order is important because this is how GlobalSearch will stitch the document back together.

Finalize Upload

  • Request: GET Chunking Upload/Finalize Upload

    • This will write the completed chunks to a file in the WebPortalCache directory, the return value from this request will be that file name. This file name is used in the last request when indexing the document.

Import Document from WebPortalCache

  • Request: POST Document Actions/Import Document from WebPortalCache

Example Body of Request:
JSON
{
    "fields": [
        {
            "name": FieldID,
            "value": IndexFieldValue
        }
    ],
    "files":[
        {"name":WebPortalCacheFilename}
    ]
}
  • Uses the WebPortalCache filename to index the document to the selected database/archive

Uploading and Indexing a Document

Postman Flow example

Steps:

Get GlobalSearch License

  • Request: GET Authentication and Licenses/Get License

  • Uses Basic Authentication using the postman {{user}} and {{password}} variables (pulled from Postman Environment)

Upload File to Server

By default it will attempt to find a PDF file called “UnsupportedDocumentFormat.pdf“ in your Postman files directory (by default this is C:\Users\<username>\Postman\files). You can update this to be whatever file you wish.

  • Request: POST Document Actions/Upload File To Server

  • Uses request body form-data to upload files

    • Note that you can add multiple files by adding more “file” keys to the form-data section.

    • Select the request and switch to the Body tab;

Index the document

  • Request: POST Document Actions/Import Document from WebPortalCache

Example Body of Request:
JSON
{
    "fields": [
        {
            "name": FieldID,
            "value": IndexFieldValue
        }
    ],
    "files":[
        {"name":WebPortalCacheFilename}
    ]
}

Running a search

Postman flow example:

See Searching/Run Search
In order to run a search you will need the following;

  • Database ID

    • Run Database/Get Database List and pick the most appropriate database from the returned list

  • Archive ID

    • Run Archives/Get Archives, pick the appropriate archive from the returned list

  • Search SecureId

    • Run Searching/Get Archive Searches to return a full list of searches for an archive, the "Hash" value in the returned information is the "SecureId" of the search.

  • Search Criteria information as needed

    • In the output of Searching/Get Archive Searches, each search will have a "Detail" object, each item is a search prompt, the "ID" value is the prompt id that will be used in the Search Critera

      • Note that the prompt ids will change if the search is modified/edited/updated.

The JSON document below is an excerpt of the information retrieved from the Searching/Get Archive Search request. Note that the “Detail” array will have a list of objects describing each Search Prompt. The “ID” key/value pair is the “Prompt Id”. The “FID” value is the GlobalSearch FieldID that the prompt will be compared against.

JSON
<truncated>
        "Hash": "245098cfd2e75673bbe3af5ad7bd46fac7e505fc988aab79766f7ea5b619a8d0",
        "Detail": [
            {
                "ID": 1,
                "FID": 1,
                "ListID": 0,
                "ListF1": 0,
                "ListF2": 0,
                "Parent": 0,
                "Operator": 2,
                "Prompt": "Character Field 1:",
                "VAL": "",
                "Prop": 0,
                "FieldType": 1,
                "Mask": ""
<truncated>

Once you have all of this information fill it out in the GlobalSearch Collection variables as desired.

For the "SearchCriteria" URL parameter, this is a JSON document that pairs Prompt IDs (retrieved from search description) with the search criteria.

CODE
{1:"tom"}

When passed in via URL param as described the above will execute the search with "tom" as the only filter criteria for search prompt 1. Postman will handle URL escaping, if you are implementing outside of Postman you will have to take steps to ensure that the search values are properly escaped, if they are not you may recieve 404s instead of an error message.

Other Parameters for Searching/Run Search

  • Page - Mainly used by GlobalSearch Web/LAN to return a limited number of results in page like fashion

  • RecordsPerPage - The number of results to return

  • SecureId - The "Hash" of the search

  • count - Only returns the number of documents found, without information about the documents themselves

Moving a Document

See Document Actions/Copy Document and Document Actions/Move Document

Please note that you should always fetch the SecureID values anytime that you need to use them, they are updated often. This applies to any version of the SecureID, whether it be search or document.

In order to move a document you will need to know the following

  • DatabaseID - GlobalSearch Database ID

    • Run Database/Get Database List and pick the most appropriate database from the returned list

  • ArchiveID - GlobalSearch Archive ID

    • Run Archives/Get Archives, pick the appropriate database from the returned list

  • DocID - GlobalSearch Document ID

    • There are many ways this is obtained, typically via running a search

  • DestinationArchiveID - GlobalSearch Archive ID that you want to move/copy the document to

  • SecureID - A unique hash of the document

    • See Document Actions/Get Document Secure ID

Updating Index data on a Document

See Document Actions/Update Index Data

In order to update index data fro a document you will need to know the following, see previous sections for how to obtain these.

  • DatabaseID - GlobalSearch Database ID

  • ArchiveID - GlobalSearch Archive ID

  • DocID - GlobalSearch Document ID

  • SecureID - A unique hash of the document

Example Body of Request:

Below is an example of the Request body used for updating index data. The “ID” key value pair refers to the FieldID on the document that you want to update the data for. The “VAL” key/value pair is the value that you want to be updated.

JSON
{
    "IndexData": {
        "IndexFields": [
            {
                "ID":1,
                "VAL":"Test"
            }
        ]
    }
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.