Apply a Policy to an App with Options

This scenario describes the steps necessary for applying the App Expiration policy to an app. App Expiration is a more advanced policy with additional options you can define.

tip

Use the links on this page to view a more detailed reference about the resource, including full sample requests and responses.

info

All the same best practices and caveats still exist when you're applying policies through the API. For more information about how to apply policies in general, see Apply Policies to an App.

Prerequisites

Before you can apply any policies, you need to determine which app you'll be applying policies to. Specifically, you need to know the app_id attribute for the app.

Send the following request:

GET /applications/

This request returns a list of all apps in your organization. Use the list to locate a specific app's app_id in the response.

Once you know the app_id, you're ready to apply policies to the app.

Back to Top

Step 1 - Know the policy you want to apply

Request List of Policies

Send the following request:

GET /policies/

This request returns a list of all policies in your organization. Use the list to locate a specific policy object in the response.

info

In the basic policy example, the configurable_fields object was null. In this example, it contains additional attributes, which indicates that the policy has additional options to define.

For example:

 {
    "display_name": "App Expiration",
    "created": "2018-01-29T09:04:23.073601+00:00",
    "auth_optional": true,
    "display_description": "Defines range of dates within which users can use the app.",
    "is_dynamic": true,
    "supports_ios": true,
    "configurable_fields": {
        "user_message": {
            "label": "Message for user:",
            "type": "text",
            "default": "This application cannot be run. The date is outside the application access period.",
            "validation": {
                "type": "string",
                "required": true
            }
        },
        "access_date_range": {
            "label": "Access Date Range",
            "type": "daterange",
            "default": {
                "start": "",
                "end": ""
            },
            "validation": {
                "required": true
            }
        }
    },
    "supports_android": true,
    "policy_id": "com.apperian.access-control",
    "id": "Aegm9Dfmsb4dSxpt8lZTjA",
    "configurations": []
},

Find the Policy ID

Locate the policy_id at the end of the appropriate policy object.

For example:

"policy_id": "com.apperian.access-control"

Back to Top

Step 2 - Apply the policy to the app

Prepare the configurations object

The apply policies resource requires a data parameter called configurations, which will contain the policy_id from the previous step. Before you send the request, you need to ensure that the configurations parameter JSON body is correct.

If you want to define a policy's additional options, you need to include an additional parameter called configuration inside configurations. In this case, with the App Expiration policy, we'll define date range and user message.

"configurations": [
      {
        "configuration": {
          "access_date_range": {
            "start": "20190301",
            "end": "20190401"
          },
          "user_message": "This application cannot be run. The date is outside the application access period."
        },
        "id": "hBrwn9xJueznIKdF5cAGaw",
        "policy_id": "com.apperian.access-control"
      }
    ]

Apply the policy

Send the the following request using the app_id and configurations parameters you retrieved previously:

POST /applications/(app_id)/policies/

Here is an example request that will apply the App Expiration policy to an app. Backslashes ( \ ) indicate line breaks in cURL syntax.

curl -X POST https://na01ws.apperian.com/v2/applications/ENRlg9bicXHvc13q7M3rsQ/policies
    --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg" --header "Content-Type: application/json"
    --data '{"configurations":[
            {"policy_id": "com.apperian.access-control",
            "configuration": {"access_date_range": {"start": "20190301", "end": "20190401"}, "user_message": "This application cannot be run. \
The date is outside the application access period."}}
]}'

For an example response, click the previous link to view the API reference.

Monitor Policy Status

The GET request to /applications/(app_id)/policies/ is asynchronous, which means you can make a request to view the policy status for an app at any time, including immediately after you send the POST request.

Send the following request:

GET /applications/(app_id)/policies/

The response will include a status attribute. For example:

 "status": {
      "code": 3,
      "description": "POLICIES NOT SIGNED"
    }

For a list of possible statuses and a description of each, see About the Policies API.

Back to Top

Next steps

Now that the policy is successfully applied to the app, you need to re-sign the app and deploy it to your users. For more information, see Re-sign an App and Signing API.

Back to Top