Service Packs Assignement Modification Analysis¶
Retrieve the impacts on adding Service Packs (among others for the Integrated Clients)¶
-
GET
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/properties/integrated_client_check_new_sp/
¶ This API will analyse the impacts of adding new Service Packs to the End User. The API will first compare the already assigned Service Packs to detect the new ones (in case the client would always send the full list of SP needed).
Then it will check what are these Service Packs that have an integrated client and if some of these Service Packs have exclusivity constraints. That logic is based on the field “integrated_client” of the Service Pack object (Display services pack instance) and more precisely on its sub-fields “mode”, “device_types” and “exclusive”.
If the check logic is enabled (see end of this page), it will be checked if the main device type is included in the integrated clients of one of the new service packs. If it is the case, the service pack will be removed from the newServicePacksWithIntClient
Example request:
GET /api/v1/tenants/foo/groups/foogroup/users/foouser/properties/integrated_client_check_new_sp/ HTTP/1.1 Host: example.com Content-Type: "application/json" { "mode": "webex", "servicePacks": [{"name": "test-sp-integrated-client-2"}, {"name": "test-sp-7"}]} }
Where “test-sp-7” is already assigned and “test-sp-integrated-client-2” has an integrated client and is mutually exclusive with “test-sp-integrated-client-1”.
Example response:
HTTP/1.1 200 OK Content-Type: "application/json" { "newServicePacks": ["test-sp-integrated-client-2"], "newServicePacksWithIntClient": ["test-sp-integrated-client-2"], "servicePackToRemove": ["test-sp-integrated-client-1"] }
- Request JSON Object:
mode (boolean) – The mode to be be analyzed. If not provided, all modes are analyzed.
servicePacks (array) – a list of service packs objects to be checked for assignment as defined in Service Assignment Status attributes.
removeExclusive (boolean) – If true if some servicePacks to be added are exclusive, the APIO will try to filter them, if false an error will be generated. If not provided the settings CHECK_SP_REMOVE_EXCLUSIVE is used with True as default value.
newMainDeviceType (string) – (optional): if a new main device type will be provisioned afterwards, it can be referenced to be used by the analysis instead of using the current one.
- Response JSON Object:
newServicePacks (array) – The list of Service Packs that are really new.
newServicePacksWithIntClient (array) – Which of the Service Packs in newServicePacks will need to create Integrated Clients.
servicePackToRemove (array) – Which currently assigned Service Packs need to be removed because referenced as “exclusive” from newServicePacksWithIntClient and they are currently assigned to the End User, and their associated integrated clients have to be deleted.
servicePackToRemoveWithIntClient (array) – Which of the Service Packs in servicePackToRemove will need to delete Integrated Clients.
excludedServicePack (array) – Which Service Packs parts of the servicePacks have been excluded because “exclusive” from newServicePacksWithIntClient.
excludedServicePackWithIntClient (array) – Which of the Service Packs in excludedServicePack were supposed to have Integrated Clients.
- Status Codes:
200 OK – no error
the request can not be executed, with possible sub-error codes:
2: INVALID_PARAMETERS, on parameters [“servicePacks”], “Some Services Packs are mutually exclusive”. It means that the user tries to assign mutually exclusive service packs.
Detailed explanation on the exclusive management in this API¶
A conflict means that one of the new services to be assigned declares to be exclusive with an other one and both are requested to be assigned (either as already assigned or part of the new list). A set of conflicts is “simple” when a SP A says to be exclusive with SP B but not the othr way around. A set of conflict is “complex” when a SP A says to be exclusive with with B but B or an other SP says also to be exclusive with A.
If removeExclusive if false and there is a conflict the the request is rejected.
If removeExclusive if true and there are conflicts “simple” the the request is accepted and the SP that were indicated as exclusive by an other SP will be included in the excluded lists.
If removeExclusive if true and there are conflicts “complex” the the request is rejected because we have the chicken-egg issue and it is impossible to decide which SP should be kept and which one should be excluded.
Retrieve the impacts on deleting Service Packs (among others for the Integrated Clients)¶
-
GET
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/properties/integrated_client_check_delete_sp/
¶ This API will analyse the impacts of removing new Service Packs from the End User. The API will first compare the already assigned Service Packs to detect the ones to be really removed.
Then it will check what are these Service Packs that have an integrated client. That logic is based on the field “integrated_client” of the Service Pack object (Display services pack instance) and more precisely on its sub-fields “mode” and “device_types”.
If the check logic is enabled (see end of this page), it will be checked if the main device type is included in the integrated clients of one of the service packs to be removed. If it is the case, the request will be rejected.
Example request:
GET /api/v1/tenants/foo/groups/foogroup/users/foouser/properties/integrated_client_check_delete_sp/ HTTP/1.1 Host: example.com Content-Type: "application/json" { "mode": "webex", "servicePacks": [{"name": "test-sp-integrated-client-2"}, {"name": "test-sp-7"}]} }
Where “test-sp-7” was not assigned and “test-sp-integrated-client-2” was assigned and has an integrated client.
Example response:
HTTP/1.1 200 OK Content-Type: "application/json" { "deleteServicePacks": ["test-sp-integrated-client-2"], "deleteServicePacksWithIntClient": ["test-sp-integrated-client-2"] }
- Request JSON Object:
mode (boolean) – The mode to be be analyzed. If not provided, all modes are analyzed.
servicePacks (array) – a list of service packs objects to be checked for un-assignment as defined in Service Assignment Status attributes.
newMainDeviceType (string) – (optional): if a new main device type will be provisioned afterwards, it can be referenced to be used by the analysis instead of using the current one.
- Response JSON Object:
deleteServicePacks (array) – The list of Service Packs that are really to be deleted.
deleteServicePacksWithIntClient (array) – Which of the Service Packs in deleteServicePacks will need to delete Integrated Clients.
- Status Codes:
200 OK – no error
the request can not be executed, with possible sub-error codes:
2: INVALID_PARAMETERS, on parameters [“servicePacks”], “Service Pack can not be removed as needed for the Main Device: …” with the … replaced by the name of the service pack causing issue. It will also be present in the sub field values of the error response
Retrieve the impacts of defining a full new set of Service Packs (among others for the Integrated Clients)¶
-
GET
/api/v1/tenants/
(string: tenant_id)/groups/
(string: group_id)/users/
(string: user_id)/properties/integrated_client_check_full_sp/
¶ This API will analyse the impacts of replacing the current list of Service Packs of the End User by a new one. The API will first compare the already assigned Service Packs to detect the ones to be added and the onces to be removed.
Then it will check what are these Service Packs that have an integrated client and if some of these Service Packs have exclusivity constraints. That logic is based on the field “integrated_client” of the Service Pack object (Display services pack instance) and more precisely on its sub-fields “mode”, “device_types” and “exclusive”.
If the check logic is enabled (see end of this page), it will be checked if the main device type is included in the integrated clients of one of the new service packs. If it is the case, the service pack will be removed from the newServicePacksWithIntClient. It will be checked fifthe main device type is included in the integrated clients of one of the service packs to be removed. If it is the case, the request will be rejected.
A special case is the migration of a of “mode” to an other one. If it is the case, it is needed to include “migrate”: true in the input data. In that case it will check if the current main device type is linked to one of the exclusive service packs of the new service packs and in that case it will return in changeMainDeviceType the new main device type that should be created.
Example request:
GET /api/v1/tenants/foo/groups/foogroup/users/foouser/properties/integrated_client_check_full_sp/ HTTP/1.1 Host: example.com Content-Type: "application/json" { "mode": "webex", "servicePacks": [{"name": "test-sp-integrated-client-2"}, {"name": "test-sp-7"}]} }
Where “test-sp-7”, “test-sp-integrated-client-1”, “test-sp-4” are currently assigned and “test-sp-integrated-client-2” and “test-sp-integrated-client-1” have an integrated client.
Example response:
HTTP/1.1 200 OK Content-Type: "application/json" { "newServicePacks": ["test-sp-integrated-client-2", "test-sp-7"], "newServicePacksWithIntClient": ["test-sp-integrated-client-2"], "deleteServicePacks": ["test-sp-integrated-client-1", "test-sp-4"], "deleteServicePacksWithIntClient": ["test-sp-integrated-client-1"] }
- Request JSON Object:
mode (boolean) – The mode to be be analyzed. If not provided, all modes are analyzed.
servicePacks (array) – a list of service packs objects to be checked for assignment as defined in Service Assignment Status attributes.
removeAllServicePacks (boolean) – Some clients does not support to send an empty array in GET parameters. In that case to indicate that alls SP needs to be removed this flag can be used. Only true is meaningful, false will be ignored.
removeExclusive (boolean) – If true if some servicePacks to be added are exclusive, the APIO will try to filter them, if false an error will be generated. If not provided the settings CHECK_SP_REMOVE_EXCLUSIVE is used with False as default value.
newMainDeviceType (string) – (optional): if a new main device type will be provisioned afterwards, it can be referenced to be used by the analysis instead of using the current one.
migrate (boolean) – (optional): if present and true, , indicate that we want to migrate and therefore the main_device could have to change.
- Response JSON Object:
newServicePacks (array) – The list of Service Packs that needs to be added
newServicePacksWithIntClient (array) – Which of the Service Packs in newServicePacks will need to create Integrated Clients.
deleteServicePacks (array) – The list of Service Packs that are really to be deleted (as no more part of the new list)
deleteServicePacksWithIntClient (array) – Which of the Service Packs in deleteServicePacks will need to delete Integrated Clients.
excludedServicePack (array) – Which Service Packs parts of the servicePacks have been excluded because “exclusive” from newServicePacksWithIntClient.
excludedServicePackWithIntClient (array) – Which of the Service Packs in excludedServicePack were supposed to have Integrated Clients.
changeMainDeviceType (string) – If migrate true and if the main device type has to be changed, it inducates what is the expected new phone type for the main device.
- Status Codes:
200 OK – no error
the request can not be executed, with possible sub-error codes:
2: INVALID_PARAMETERS, on parameters [“servicePacks”], “Some Services Packs are mutually exclusive”. It means that the user tries to assign mutually exclusive service packs.
2: INVALID_PARAMETERS, on parameters [“servicePacks”], “Service Pack can not be removed as needed for the Main Device: …” with the … replaced by the name of the service pack causing issue. It will also be present in the sub field values of the error response
Detailed explanation on the exclusive management in this API¶
A conflict means that one of the new services to be assigned declares to be exclusive with an other one and both are requested to be assigned (as part of the new list). A set of conflicts is “simple” when a SP A says to be exclusive with SP B but not the othr way around. A set of conflict is “complex” when a SP A says to be exclusive with with B but B or an other SP says also to be exclusive with A.
If removeExclusive if false and there is a conflict the the request is rejected.
If removeExclusive if true and there are conflicts “simple” the the request is accepted and the SP that were indicated as exclusive by an other SP will be included in the excluded lists.
If removeExclusive if true and there are conflicts “complex” the the request is rejected because we have the chicken-egg issue and it is impossible to decide which SP should be kept and which one should be excluded.
Configuration Settings¶
The APIO behaviour is controlled by the following settings:
"CHECK_INTEGRATED_CLIENT_MAIN_DEVICE" : true
- Explanation for the parameters:
CHECK_INTEGRATED_CLIENT_MAIN_DEVICE: if enabled the APIO will check the Main Device Type and will apply the logic described in the different APIs. Default is true. Logic introduced in 1.8.3.
Note
- In order to have the the check logic working correctly a standard basic setup is needed:
only one integrated client device_type by service pack
only a device_type is present as integrated client in maximum one service pack
the mandatory specific services needed by an integrated client device_type are only present in the related service packs not in other generic service packs.
If these conditions are not met, the related check logics can lead to unpredictable results and it therefore recommended to disable them and manage the checks at api client side by several api calls to the related end points (service packs definition, user main device, …)