Create a Preset Configuration
This scenario describes the steps necessary for creating preset configurations for a specific policy, so you can refer to and use them later when applying the policy to an app. For more information about preset configurations, see Policy Configurations.
Use the links on this page to view a more detailed reference about the resource, including full sample requests and responses.
:::
For the purpose of this scenario we'll look at the Open Web Page policy, which opens a browser window to a specified web page after the user opens the app a predefined number of times. You could create a number of preset configurations for different websites.
The Policies API allows you to create and manage multiple preset configurations for each policy (the Admin Portal only allows you to configure one preset on the Policies page).
Step 1 - Know the policy
Before you can create a preset configuration you need to know which policy you're creating the configuration for.
Request List of Policies
Send the following request:
This request returns a list of all policies in your organization. Use the list to locate a specific policy object in the response.
For example:
{
"policies": [
{
"display_name": "App Usage",
"created": "2018-01-29T09:04:23.073601+00:00",
"auth_optional": true,
"display_description": "Tracks whenever users opens the app, foregrounds the app, or returns to the app from the lock screen.",
"is_dynamic": true,
"supports_ios": true,
"configurable_fields": null,
"supports_android": true,
"policy_id": "com.apperian.app-usage",
"id": "XWJKqWeLM5-tp8N09-gTEw",
"configurations": []
},
{...}
{
"display_name": "Open Web Page",
"created": "2018-01-29T09:04:23.073601+00:00",
"auth_optional": false,
"display_description": "Opens a browser window to a specified web page after a user opens the app a set number of times.",
"is_dynamic": true,
"supports_ios": true,
"configurable_fields": {
"open_webpage_frequency": {
"label": "Frequency",
"type": "text",
"default": "1",
"validation": {
"type": "number",
"required": true,
"min": 1
}
},
"open_webpage_url": {
"label": "Web Page URL",
"type": "text",
"default": "",
"validation": {
"type": "url",
"required": true
}
}
},
"supports_android": true,
"policy_id": "com.apperian.open-webpage-url",
"id": "A4jwZ8qBV5bf53AeA6lrNA",
"configurations": [
{
"name": null,
"auth_required": true,
"enabled_by_default": true,
"is_a_preset": true,
"created_time": "2015-11-16T01:05:44.374411+00:00",
"configuration": {
"open_webpage_url": "https://www.example.com/appsurvey.htm",
"open_webpage_frequency": "5"
},
"id": "W7P-GCTcUq5fKYg2jGu7kQ",
"policy_id": "com.apperian.open-webpage-url"
}
]
}
{...}
]
}
Find the Policy ID
Locate the policy_id in the response.
For example:
"policy_id": "com.apperian.open-webpage-url"
The /policies/(policy_id)/configurations/ resource accepts either the policy_id value or the id value in the URL, but for this example we are using policy_id.
Step 2 - Identify the policy's options
The create preset resource can include up to 3 data parameters, the most complex of which is configuration. For a description of each data parameter, see Create a Preset Policy Configuration.
The configuration parameter defines the options for the preset configuration. To find which options are available for including in the configuration parameter, you need to look at the response from GET /policies/ or GET /policies/(policy_id)/. The response includes a configurations array, inside which may be 1 or more nested objects. The availably policy options are listed within the configuration attribute.
Here is an example of the high-level configurations array with one nested configuration:
"configurations": [
{
"name": null,
"auth_required": true,
"enabled_by_default": true,
"is_a_preset": true,
"created_time": "2015-11-16T01:05:44.374411+00:00",
"configuration": {
"open_webpage_url": "https://www.example.com/appsurvey.htm",
"open_webpage_frequency": "5"
},
"id": "W7P-GCTcUq5fKYg2jGu7kQ",
"policy_id": "com.apperian.open-webpage-url"
}
]
And here is the configuration attribute:
"configuration": {
"open_webpage_url": "https://www.example.com/appsurvey.htm",
"open_webpage_frequency": "5"
},
From this example we see that the configuration attribute includes two options called open_webpage_url and open_webpage_frequency. Other policies may include more or fewer options.
If for some reason the configurations array appears null (which may happen if all of the presets are deleted) you can look at the configurable_fields policy object. The configurable_fields object lists all of the policy's options (with other data that you can ignore) but no values.
For example:
{
"policy": {
"display_name": "Open Web Page",
"created": "2018-01-29T09:04:23.073601+00:00",
"auth_optional": false,
"display_description": "Opens a browser window to a specified web page after a user opens the app a set number of times.",
"is_dynamic": true,
"supports_ios": true,
"configurable_fields": {
"open_webpage_frequency": {
"label": "Frequency",
"type": "text",
"default": "1",
"validation": {
"type": "number",
"required": true,
"min": 1
}
},
"open_webpage_url": {
"label": "Web Page URL",
"type": "text",
"default": "",
"validation": {
"type": "url",
"required": true
}
}
},
Here, you can see the same open_webpage_url and open_webpage_frequency options as before.
Step 3 - Prepare the Data Parameters
Now that we know the available options, we can modify them and ensure that the configurations parameter JSON body is correct before sending the request. If you know that you'll have multiple presets, you can provide each with a unique name. You can also set the policy to be enabled by default which means it will automatically appear selected in the Admin Portal on an app's Policies tab.
{
"name": "Survey1",
"enabled_by_default": true,
"configuration": {
"open_webpage_url": "https://www.example.com/survey1.md",
"open_webpage_frequency": "5"
},
}
Step 4 - Create the preset
Send the following request using the policy_id and data parameters you retrieved and customized previously:
POST /policies/(policy_id)/configurations/
Here is an example request. Backslashes ( \ ) indicate line breaks in cURL syntax.
curl -X GET https://na01ws.apperian.com/v2/policies/com.apperian.open-webpage-url/configurations/
--header "Content-Type: application/json" --header "X-TOKEN: yCczCnsNSJyW_3JyS6YwAQ"
--data '{"enabled_by_default": true,
"name": "Survey1",
"configuration": {
"open_webpage_url": "https://www.example.com/survey1.md",
"open_webpage_frequency": "1"
}}'
For an example response, click the previous link to view the API reference.
Next Steps
Our fictional company that has multiple organizations will likely want to create a unique preset for each organization by repeating steps 3 and 4 for any additional presets.
When one or more presets exist, you can retrieve and use them later when applying the policy to an app. For more information, see Use a Preset Configuration.