Submit a Group Client for Processing

This operation provides the ability to submit a Group Client for processing. For details about the processing of group clients refer to section Process Group Clients in the Policies Operations Guide.

Resource Representation

Group Clients can be submitted independent of their status.

The resource representation of a groupClient looks like this:

{
... group client properties ...
"links": [
{
"href": "http://<host>:<port>/[api-context-root]/generic/groupclients/<id>",
"rel": "self"
},
{
"href": "http://<host>:<port>/[api-context-root]/groupclients/<id>/submit",
"rel": "groupclient:submit",
"httpMethod": "POST"
},
{
"href": "http://<host>:<port>/[api-context-root]/groupclients/<id>/status",
"rel": "groupclient:status"
}
]
}

Unlike the submitting of a policy for processing, the option of submitting a group client for processing does not depend on the status of the group client.

API Conversation and Interaction

The conversational and interaction style of this API is based on its asynchronous nature. The client of this API will become detached from the actual background process. The client can use the "status" resource (explained later) to monitor that background process. So the client of the API is not blocked, but rather is provided with the means to track progress in an asynchronous fashion.

When this process completes this means that either the group client has been processed or that there were errors during processing. Both of these outcomes are made available/accessible for the consumer of this API.

Resources Used in This API

Group Client Resource

This is a singular resource representing a group client. For more details about the representation, see Default Resource Representation (GET). The group client resource contains the "submit" link and the link to the "status" resource.

Status Resource

This resource provides the option to track the result of the processing and the ability to show processing errors. As these are individual states of the application, we have to define the various link relations to allow a consumer to have a conversation with the system.

Link Relations Used in This API

In the case of submitting a group client for processing, the following link relations are defined.

rel="groupclient:submit"

To eventually have a group client - in the context of this link relation - processed by the system.

rel="groupclient:status"

To request the status of the current or last group client submit action.

rel="self"

Link to the current resource. This for instance can be used on the status resource to periodically poll the resource for progress tracking.

rel="related"

This is a standard link relation to the related (group client) resource. This should be provided once the request is completed successfully.

Interaction Messages

The client requests a group client. The group client is returned like this:

{
  ... group client properties ...
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/groupclients/<id>",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/groupclients/<id>/submit",
      "rel": "groupclient:submit"
      "httpMethod": "POST"

    }
  ]
}

The client submits the groupClient by calling POST on "api-context-root/groupClient/<id>/submit". The group client processing is started, and the server responds with status 201. A link to the status resource is returned in the Location header like this:

Location: http://<host>:<port>/[api-context-root]/groupclients/<id>/status

The clients can now track the progress by issuing a GET to the status URI returned in the Location header. While the groupClient is being processed, the status resource will be returned like this:

{
  "progress": "processing",
  "completed": false,
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/groupclients/<id>/status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/groupclients/<id>",
      "rel": "related"
    }
  ]
}

When the processing ends successfully (no errors), the status resource will return:

{
  "progress": "succeeded",
  "completed": true,
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/groupclients/<id>/status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/groupclients/<id>",
      "rel": "related"
    }
  ]
}

When the processing ends unsuccessfully, the status resource returns:

{
  "progress": "failed",
  "completed": true,
  "o:errorDetails": [
    {
     "detail": "<detailed activity message 1>",
      "o:errorCode": ""

   },
    {
      "detail": "<detailed activity message 2>",
      "o:errorCode": ""
    }
  ],
"links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/groupclients/<id>/status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/groupclients/<id>",
      "rel": "related"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/activities/<id>/recover",
      "rel": "oi:reprocess"
    }
  ]
}

Authorization

The above described operation is protected by access restriction "groupclient.submit IP". A grant for this access restriction must be provided. If the access to a group client is restricted by a data access group restriction, then to perform this operation on that group client also a grant for that data access group restriction must be provided with the Update flag set. A read grant must also be given to access the group client resource.