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)/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 Tenant Admin.

Example request:

GET /api/v1/tenants/foo/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:

200 OK – request is ok

Deleting several asynchronous jobs¶

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

Authorization rights: minimum Tenant 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)/bulks/results/(string: job_id)/¶

Authorization rights: minimum Tenant Admin.

Example request:

GET /api/v1/tenants/foo/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",
     "status": "success",
     "description": "dnd",
     "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.

Status Codes:

200 OK – request is ok

Deleting one asynchronous job¶

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

Authorization rights: minimum Tenant Admin.

Example request:

DELETE /api/v1/tenants/foo/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:

200 OK – request is ok

Objects definition¶

User’s Service Bulk Jobs items¶

Name	Type	Methods	Description
Name	Type	GET	Description
job_id	String	A	The Job ID (UUID4).
job_type	String	A	The type of job: BULK_USER_SRV_UPDT or OTHER.
description	String	A	A description of the purpose of the job.
status	String	A	The status of the bulk job: ‘queued’, ‘ongoing’, failed’, ‘partial_success’, ‘success’.
start_time	Object	A	The start date&time.
stop_time	DateTime	O	The stop date&time.
result_data	Object	O	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.