Clear Background Connector

The Clear Background connector is used to make long-running, asynchronous calls into other Clear composite APIs (aka bots). There are five operations available: CreateJob, AddTasks, GetJob, GetTasks, GetTaskResults.

The general usage pattern is: CreateJob -> AddTasks -> GetTaskResults

GetJob and GetTasks can be used to gather information about running jobs. The primary difference between GetTasks and GetTaskResults is that the former returns a truncated set of information about the tasks in question. Results from Clear APIs can be quite large, which makes responses from GetTaskResults rather long at times.

CreateJob

Creates a job and returns a job number. This is a container for all running tasks, and creating it is the first step in defining a job. Jobs may be tagged with any number of strings to aid in finding related jobs and runs. ClearBackground is intentionally “dumb,” to allow for flexibility in the way that it is used.

The CreateJob task is also responsible for gathering and storing any credentials that will be used during the process. These credentials are stored in an encrypted manner with the help of AWS Secrets Manager.

Parameters

tags (optional)

A list of strings that can later be used to retrieve related jobs.

credentials (optional)

Additional credentials may be supplied to the CreateJob function when the user running the job does not have the correct credentials to execute the underlying tasks.

  • credential_type: Two types of credentials are accepted: password and cert
  • system_username: The username in the underlying system
  • system_id: An integer identifying the ClearProcess System that these credentials are intended for
  • secret: The password or certificate

Returns

Information about the Job that was just created. The UUID is used for referencing this job in other calls.

Example:

{
  "uuid": "2598ee82-dd63-412c-b57e-57ca1cc0d4c1",
  "complete": false,
  "completed_task_count": 0,
  "tags": [
    "Test Job"
  ],
  "created": "2019-08-07T08:49:14.342456+00:00",
  "task_count": 0,
  "subdomain": "sbx.clearui.com",
  "clear_username": "dustin"
}

AddTasks

Parameters

job_id

The UUID for the job to add tasks to.

tasks

A list of tasks, each with the following parameters:

  • api_name: The API name to execute (e.g. CreateSalesOrder)
  • parameters: A dictionary of parameters expected by the API. These are passed on to ClearProcess as-is.

example:

"tasks": [
            {
                'api_name': 'GetCustomer', 
                'parameters': {'id': 1}
            },
            {
                'api_name': 'GetCustomer', 
                'parameters': {'id': 1}
            }
        ]

Returns

Success or failure message

GetJob

Get information about a job or jobs. This information includes when the job was created, how many total tasks are in the job, how many are complete, etc. This function always returns a list.

Parameters

tags

Find jobs by tags. Tags are ANDed together. A job with all the given tags will be returned.

created_before

Find jobs created before a date

created_after

Find jobs created after a date

Returns

Information about the selected jobs.

Example:

[
    {
        "completed_task_count": 0,
        "clear_username": "dustin",
        "subdomain": "sbx.clearui.com",
        "complete": false,
        "created": "2019-08-07T08:49:14.342456+00:00",
        "uuid": "2598ee82-dd63-412c-b57e-57ca1cc0d4c1",
        "task_count": 0
    }
]

GetTasks

Get abbreviated information about a job’s tasks. Note the results are paged, and only the first 100 results will be returned by default; set offset and limit to get later pages.

Parameters

job_id

The UUID of the job

offset

Default: 0

The first task to retrieve.

limit

Default: 100

The total number of tasks to return

Returns

Job information which includes a list of tasks with abbreviated information. (does not include API call results)

Example:

{
    "complete": true,
    "uuid": "9ff02735-46ce-4f84-9788-e38420edd7d8",
    "clear_username": "dustin",
    "subdomain": "sbx.clearui.com",
    "completed_task_count": 2,
    "task_count": 2,
    "created": "2019-07-25T14:59:53.548991+00:00",
    "tasks": [
        {
            "error": true,
            "api_name": "GetUserAuthorizations",
            "completed_at": "2019-07-25T15:02:46.463971+00:00",
            "uuid": "298cb0a7-2f50-4640-8c07-535f5ffb0186",
            "created": "2019-07-25T15:00:14.982719+00:00",
            "sequence_num": 0
        },
        {
            "error": true,
            "api_name": "GetUserAuthorizations",
            "completed_at": "2019-07-25T15:00:21.405760+00:00",
            "uuid": "06c11f76-4e95-4628-b02a-df0e99524a68",
            "created": "2019-07-25T15:00:14.982804+00:00",
            "sequence_num": 1
        }
    ]
 }

GetTaskResults

Get full information about a job’s tasks, including the results of the Task API calls. Note the results are paged, and only the first 100 results will be returned by default; set offset and limit to get later pages.

Parameters

job_id

The UUID of the job

offset

Default: 0

The first task to retrieve.

limit

Default: 100

The total number of tasks to return

Returns

Job information which includes a list of tasks with abbreviated information. (does not include API call results)

Example:

{
  "complete": true,
  "uuid": "9ff02735-46ce-4f84-9788-e38420edd7d8",
  "clear_username": "dustin",
  "subdomain": "sbx.clearui.com",
  "completed_task_count": 16,
  "task_count": 16,
  "created": "2019-07-25T14:59:53.548991+00:00",
  "tasks": [
    {
      "error_detail": "",
      "error": false,
      "result": {
        "errors": [],
        "new_rpc": true,
        "payload": {
          "GetUserAuthorizations": {
            "Auth_Count": 2990,
            "Auth_List2": true,
            "Authorizations": {
              "WLM": {
                "LAYGR": "*"
              },
              "D_IR": {
                "ACTVT": "*",
                "SPART": "*",
                "VKORG": "*",
                "VTWEG": "*",
                "PARTNER": "*"
              },
              [...]
              "W_WXP_HIER": {
                "ACTVT": "*",
                "PLHVS": "*",
                "PLSZN": "*"
              },
              "W_WXP_PLAN": {
                "ACTVT": "*",
                "PLSCH": "*",
                "PLSZN": "*"
              }
            }
          }
        },
        "_timings": {
          "overall": "0.638299942017",
          "Auth_List2": "0.599851846695"
        }
      },
      "api_name": "GetUserAuthorizations",
      "completed_at": "2019-07-25T15:02:46.463971+00:00",
      "uuid": "298cb0a7-2f50-4640-8c07-535f5ffb0186",
      "parameters": {},
      "created": "2019-07-25T15:00:14.982719+00:00",
      "sequence_num": 0
    },
    {
      "error_detail": "",
      "error": true,
      "result": {
        "errors": [],
        "new_rpc": true,
        "payload": {
          "GetUserAuthorizations": {
            "Auth_Count": 2990,
            "Auth_List2": true,
            "Authorizations": {
              "WLM": {
                "LAYGR": "*"
              },
              "D_IR": {
                "ACTVT": "*",
                "SPART": "*",
                "VKORG": "*",
                "VTWEG": "*",
                "PARTNER": "*"
              },
              [...]
              "W_WXP_HIER": {
                "ACTVT": "*",
                "PLHVS": "*",
                "PLSZN": "*"
              },
              "W_WXP_PLAN": {
                "ACTVT": "*",
                "PLSCH": "*",
                "PLSZN": "*"
              }
            }
          }
        },
        "_timings": {
          "overall": "0.840951919556",
          "Auth_List2": "0.718284130096"
        }
      },
      "api_name": "GetUserAuthorizations",
      "completed_at": "2019-07-25T15:00:21.405760+00:00",
      "uuid": "06c11f76-4e95-4628-b02a-df0e99524a68",
      "parameters": {},
      "created": "2019-07-25T15:00:14.982804+00:00",
      "sequence_num": 1
    }
  ]
}