App Save Configuration URL endpoint
This endpoint is invoked by AMS on application configuration save. This topic explains the details of the request sent from AMS to an app when an app's configuration changes are saved. For information on the entire application configuration workflow see App Configuration.
Service URL
<app-base-url><app-save-configuration-url>
These URLs are registered with AMS when creating an app.
Request Method
POST
Request Header
Authorization: Bearer <JWT>
Content-Type=application/json
Bearer Token
JWT claims
When AMS is making the request to the app, the key and value pairs bear the following meanings:
Key | Value Definition | Context |
---|---|---|
iss
|
The current issuer of the token. | Set to "AMS". |
sub
|
The subject of the token. | Set to the app's product UUID. |
aud
|
The audience of the token. | Set to the app's Token Key. |
exp
|
The date and time the token will expire, expressed as a Unix timestamp. Must be after the current date/time. | Set to 60 seconds after the JWT was created. |
iat
|
The date and time the JWT was issued, expressed as a Unix timestamp. | Set to the current time. |
jti
|
The unique identifier for the JWT token. | Set to a random UUID. |
o.a.p.ctenantId
|
The tenant Id. | Set to the id of the tenant as identified by the product. |
o.a.p.capplicationUUID
|
The application UUID. | Set to the application UUID. |
o.a.p.cproductUUID
|
The product UUID. | Set to the UUID of the product associated with the current installation. |
o.a.p.cproductName
|
The product name. | Set to the name of the product, associated with the current installation. |
o.a.p.csourceRequest
|
The Source Id. | Set to the UUID of the product associated with the current installation. |
o.a.p.cdestinationId
|
The destination Id. | Set to the app's UUID. Found in app details. |
Signature
Signed with an app's token secret.
Sample JWT Payload
Below is an example JWT payload that AMS uses to call the app's Save Configuration URL endpoint:
{
"iss": "280e7a65-ab6f-47ce-9dfd-0949fcca304c",
"sub": "<app-product-uuid>",
"aud": "280e7a65-ab6f-47ce-9dfd-0949fcca304c",
"exp": 1549569271,
"iat": 1549569211,
"jti": "143c9f36-382b-4474-8415-6800e727b477",
"o.a.p.ctenantId": "607",
"o.a.p.capplicationUUID": "64658070-8290-4e2b-90d3-ec28fe01321e",
"o.a.p.cinstallUUID": "709557d8-3af1-498a-ac8c-2c336cb9e415",
"o.a.p.cproductUUID": "ba2e2ebc-2160-4ecc-b0d8-39f2ed20271f",
"o.a.p.csourceRequest": "<app-product-uuid>",
"o.a.p.cdestinationId": "709557d8-3af1-498a-ac8c-2c336cb9e415",
"o.a.p.cdestinationUrl": "http://localhost:8090/api/appInstalls/saveConfigure"
}
Sample Request Body
{
"installUuid": "some-install-uuid",
"payload": {
// Defined by developer. Whatever is sent in postMessage from Configure Page.
}
}
Sample Response in case of success
The apps Save Configuration URL endpoint should respond with a configurationStatus
, which would be one of the following: UNCONFIGURED, CONFIGURED, or ERROR. Optionally, a payload
can also be sent back to and handled by the application configuration UI. See App Configuration for details.
Sample Code
Sample App's Response Payload to Save Configuration URL Request
{
"configurationStatus": "CONFIGURED"
}
Sample App Implementation: Save Configuration URL Endpoint
//AppInstallController.java
@RequestMapping(value = "/saveConfigure", method=RequestMethod.POST)
public AppInstallConfigurationChangeStatusDTO saveConfigureAppInstall(@RequestBody AppInstallSaveConfigDTO body) throws JSONException, IOException {
String installUuid = body.getInstallUuid();
AppInstall install = appInstallService.getEntity(installUuid);
if(install == null) {
throw new EntityNotFoundException("App Install Not Found => " + installUuid);
}
install.setConfig(objectMapper.writeValueAsString(body.getPayload()));
appInstallService.updateEntity(install);
AppInstallConfigurationChangeStatusDTO status = new AppInstallConfigurationChangeStatusDTO();
status.setConfigurationStatus(AppConfigurationStatusType.CONFIGURED);
return status;
}
Sample App Implementation: Response DTO
//AppInstallConfigurationChangeStatusDTO.java
@Getter
@Setter
public class AppInstallConfigurationChangeStatusDTO {
private AppConfigurationStatusType configurationStatus;
}
//AppConfigurationStatusType.java
public enum AppConfigurationStatusType {
ERROR, CONFIGURED, UNCONFIGURED;
}