Retrieve the status of bulk asynchronous jobs

When a bulk job is launched in asynchronous mode its status and result has to be fetched later.

It must also ne noted that the APIO can be configured to deleted automatically (cronjobs) old bulk job results. It would then be normal to not see anymore old results

Fetching the list of bulk asynchronous jobs

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/bulks/results/

Allow to fetch all the bulk asynchronous jobs for this Tenant.

It is possible to apply some query filters to restrict the list.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/bulks/results/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
    "job_type": "BULK_USER_SRV_UPDT"
}
Request JSON Object:

  • job_type (string) – (Optional) an optional filter on one type of jobs to be returned. One of “BULK_USER_SRV_UPDT” or “OTHER” (other will be added in the future)

  • job_types (array) – (Optional) an optional filter on several types of jobs to be returned. Mutually exclusive with job_type

  • withResult (boolean) – (Optional) if set to true, the jobs returned will contain the results (note that they could be partial if the job is not yet finished)

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
    "asynchJobs": [
      {
        "job_id": "03d0cf03-c039-4342-9a81-ddbbc719e862",
        "job_type": "BULK_USER_SRV_UPDT",
        "description": "dnd",
        "status": "ongoing",
        "start_time": "2023-01-18T11:58:42.430919+01:00"
      },
      {
        "job_id": "7eb0a94a-b416-4378-8403-6a47093b2bbf",
        "job_type": "BULK_USER_SRV_UPDT",
        "description": "dnd",
        "status": "success",
        "start_time": "2023-01-18T11:58:42.701768+01:00",
        "stop_time": "2023-01-18T11:58:42.975450+01:00"
      },
      {
        "job_id": "589fd0a5-f0ce-4455-a722-d33b8af7cbb0",
        "job_type": "BULK_USER_SRV_UPDT",
        "description": "cfa_vm",
        "status": "success",
        "start_time": "2023-01-18T11:58:43.044102+01:00",
        "stop_time": "2023-01-18T11:58:43.439136+01:00"
      },
      {
        "job_id": "fdbd0a0d-5c0a-4315-aa39-e40dc6405302",
        "job_type": "BULK_USER_SRV_UPDT",
        "description": "cfb",
        "status": "failed",
        "start_time": "2023-01-18T11:58:43.497400+01:00",
        "stop_time": "2023-01-18T11:58:44.389730+01:00"
      }
    ]
}
Response JSON Object:

  • asynchJobs (array) – a list of objects describing the asynch bulk jobs. See User’s Service Bulk Jobs items for the definition of the objects in the array.

Status Codes:

Deleting several asynchronous jobs

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/bulks/results/

Authorization rights: minimum Group Admin.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/bulks/results/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "job_ids": ["03d0cf03-c039-4342-9a81-ddbbc719e862", "fdbd0a0d-5c0a-4315-aa39-e40dc6405302"]
}
Request JSON Object:

  • job_ids (array) – (Mandatory) the ids (string) of the jobs to be deleted.

  • force (boolean) – (Optional) if set, the job is deleted whatever its status. Fo not set (default) then only finished jobs will be deleted. This parameter should be use very cautiously.

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}
Status Codes:

  • 200 OK – all jobs that could have been deleted have been deleted. It is in best effort mode, so no error is returned fir unknown jobs or jobs that can not be deleted.

Fetching the details of one asynchronous job

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/bulks/results/(string: job_id)/

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/bulks/results/03d0cf03-c039-4342-9a81-ddbbc719e862/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
     "job_id": "27863f98-ea86-437a-9196-eb5c5a718913",
     "job_type": "BULK_USER_SRV_UPDT",
     "description": "dnd",
     "status": "success",
     "start_time": "2023-01-18T11:58:40.968130+01:00",
     "stop_time": "2023-01-18T11:58:42.355763+01:00",
     "input_data": {
        "userIds": [
           "ApioUserTest@sip.netaxis.be",
           "ApioUserTest1@sip.netaxis.be"
        ],
        "referenceUserId": "ApioUserTest@sip.netaxis.be",
        "tenant_id": "ApioSpTest",
        "group_id": "ApioGrpTest",
        "instance_name": "dnd",
        "serviceName": "dnd"
     },
     "result_data": {
        "result": [
           {
              "userId": "ApioUserTest@sip.netaxis.be",
              "status": "updated"
           },
           {
              "userId": "ApioUserTest1@sip.netaxis.be",
              "status": "updated"
           }
        ]
     }
}
Response JSON Object:

  • job_id (string) – The id of the job.

  • job_type (string) – The type of job: BULK_USER_SRV_UPDT or OTHER.

  • description (string) – A description of the purpose of the job. In case of BULK_USER_SRV_UPDT it is the name of the service that is updated.

  • status (string) – The status of the bulk job: ‘queued’, ‘ongoing’, failed’, ‘partial_success’, ‘success’.

  • start_time (string) – The start date & time of the bulk job.

  • stop_time (string) – The stop date & time of the bulk job, if the job is completed.

  • input_data (object) – The input data used to trigger the job, they depend on the job itself.

  • result_data (object) – The result data that would have generated the job if called synchronously, they depend on the job itself; see the related job type to get the details on the structure.

Status Codes:

Deleting one asynchronous job

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/bulks/results/(string: job_id)/

Authorization rights: minimum Group Admin.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/bulks/results/03d0cf03-c039-4342-9a81-ddbbc719e862/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}
Status Codes: