Custom HTTP Resources

Recently we have added a new kind of resource, the http kind.

This custom resource enables the creation of complex data flows for retrieving files from HTTP endpoints. It allows for document retrieval in any of the existing inspections.

Next, we can see how to leverage this feature.

Create an HTTP Resource

We will create a two-step process, first authenticate and obtain a token and in a subsequent step we use the token to download the file during the inspection

The custom resource would look like this:

curl --request POST \
     --url https://verify-automation-api.globalvision.co/resources \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     --header 'x-org-id: <your_org_id>',
     --header 'x-api-key: <your_api_key>'
     --data '
{
  "resourceType": "input",
  "properties": {
    "type": "http",
    "steps": [
      {
        "name": "auth",
        "order": 1,
        "exports": {
          "access_token": "{{auth.response.body.access_token}}"
        },
        "request": {
          "url": "https://my_auth_url.com",
          "method": "POST",
          "headers": {
            "user": "my_user",
            "password": "my_password"
          }
        }
      },
      {
        "name": "downloadFile",
        "order": 2,
        "request": {
          "url": "https://file-download.com",
          "method": "GET",
          "headers": {
            "x-api-key": "{{auth.access_token}}"
          },
          "urlParams": {
            "fileName": "{{jobParameters.documentId}}"
          }
        }
      }
    ]
  }
}
'

The response to a request like the one shown will be a json object containing an ID, which should be provided when submitting a job:

{
  "id": "8e3b0e39-7b68-4450-9b00-742afe44239f"
}

Submit a job and provide the resource id

Once we have created a resource we can proceed to submit an inspection utilising it.

For example, we could do so on a spelling inspection ( or any other inspection for that matter ) in the following way:

curl --request POST \
     --url https://verify-automation-api.globalvision.co/inspections/spelling \
     --header 'X-Api-Key: <my_api_key>' \
     --header 'X-Org-Id: <my_org_id>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "jobs": [
    {
      "documentId": "mydocument.pdf",
      "inputResource": {
        "inputId": "8e3b0e39-7b68-4450-9b00-742afe44239f"
      }
    }
  ]
}
'

Variable substitution

Any step may need values that exist as part of the request when submitting an inspection or part of previous steps defined in the custom resource. So let's explore what can be done.

Limitations

1. It assumes every URL called on the steps will return a JSON response, except for the last one where we assume it's the file
2. The values used for replacement should be either from fields passed in the request when creating the inspection or from previous steps.
3. Error handling is quite optimistic, if any substitution or request fails the whole inspection may fail.

Export values for future usage

If we want to "persist" state we can do so by creating entries in the exports object. This will make it so that the exported value can be accessed using the pattern <step_name>.<key_name>.

As shown in the example, if we want to "persist" a value from the response the way to do it would be

{
  ...
  "name": "step1"
  "exports": {
    "mykey": "{{step1.response.body.body_field1}}",
    "mykey2": "{{step1.response.body.body_field2}}"
  }
  ...
}

Types of value substitution

Values from the request when creating the inspection

When desired, the substitution of values that are part of the request can be done using the prefix jobParameters. As of now only documentIdis supported but when wanting to do a value substitution we can do so by passing {{jobParameters.documentId}} and the automation engine will take care of the replacement.

Values from previous steps

Every step can optionally export fields as seen above, the values exported in the previous block we could access as follows:

• step1.mykey: Whatever value mykey holds from the exported section of step1
• step1.mykey2: Whatever value mykey2 holds from the exported section of step1