Table Of Contents

Policy Management Functions

asyncExecutePolicy

createPolicy

deletePolicy

enumerateDeviceFilterAttribute

enumerateSKUFilterAttribute

listAllPolicies

listFilteredDevices

listFilteredSKUs

readPolicy

writePolicy

Policy Management Functions

---

This chapter provides information about the following policy management functions:

•asyncExecutePolicy

•createPolicy

•deletePolicy

•enumerateDeviceFilterAttribute

•enumerateSKUFilterAttribute

•listAllPolicies

•listFilteredDevices

•listFilteredSKUs

•readPolicy

•writePolicy

asyncExecutePolicy

Synopsis

String asyncExecutePolicy(UserToken token, String policy_id, IDStatusListener listener);

Description

This function executes the given policy by using the policy filters to select devices and stock-keeping units (SKUs) and obtain and deploy licenses for those devices.

This function is nonblocking and returns a request ID to the caller immediately. When calling this function, a client program provides a listener object that implements StatusListener interface. When the function is completed, the onStatus() method in the listener object is invoked.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
policy_id	String, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	ID of the Policy object.
listener	IDStatusListener, mandatory	—	The listener object.

Return

This function returns a request ID to the caller. When the operation is complete, the status is provided as the input parameter of onStatus() method.

The listener will receive the IDStatus, which includes a list of IDStatusItem. Each IDStatusItem contains the PAK ID + "-::-" + SKU name + "-::-" + UDI, and the error code and error message of the operation.

Error and Exception

The input parameter of the onStatus() method in the IDStatusListener contains the error code and messages. More than one error code and message may be contained in the IDStatus object. Each ID in the status object represents a device ID that participates in the execution of the policy.

The following example shows the error code and message in the onStatus() method:

	public void onStatus(IDStatus status) {

		// The general error code of the operation.

		int err_code = status.getErrorCode();

		// The general error message of the operation.

		String err_msg = status.getErrorMessage();

		// A list of status for each individual element in the 

		// bulk operation.

		IDStatusItem[] items = status.getIDStatusItems()

		// Iterate through the list to get individual status.

	for (int i = 0; i < items.length(); i++) {

		// Get the individual object ID returned by the 

		// operation.

		String id = items[i].getID();

		// Get the individual error code corresponding to 

		// the object ID.

		int item_err_code = items[i].getErrorCode();

		// Get the individual error message corresponding to 

		// the object ID.

		String item_err_msg = tems[i].getErrorMessage();

		}

}

createPolicy

Synopsis

PolicyStatus createPolicy(UserToken token, String policy_name, SKUFilter sku_filter, 
DeviceFilter dev_filter);

Description

This function creates a Policy object that represents a set of rules for selecting SKUs and devices from the inventory.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
policy_name	String, mandatory	—	Name of the Policy object.
sku_filter	SKUFilter, optional	—	The input SKUFilter object specifies the criteria for searching the devices that match the criteria. If the filter is set to null, filtering is not performed.
dev_filter	DeviceFilter, optional	—	The input DeviceFilter object specifies the criteria for searching the devices that match the criteria. If the filter is set to null, filtering is not performed.

Return

This function returns a PolicyStatus object. The Status and the Policy object are contained in PolicyStatus. The definition of PolicyStatus and Status class is as follows:

public class Status implements Serializable {

      private int m_error_code;

      private String m_error_message;

}

public class PolicyStatusItem extends Status implements Serializable {

	private Policy m_policy;

	public Policy getPolicy() {

		return m_policy;

	}

	public void setPolicy(Policy policy) {

		this.m_policy = policy;

	}

}

Error and Exception

When an error occurs, the error code is contained in the PolicyStatus object.

deletePolicy

Synopsis

Status deletePolicy(UserToken token, String policy_name);

Description

This function deletes from the system the policy object identified by the given name.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
policy_name	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	Name of the Policy object.

Return

This function returns Status objects.

Error and Exception

When an error occurs, the information is contained in the returned status object.

enumerateDeviceFilterAttribute

Synopsis

String[] enumerateDeviceFilterAttribute(UserToken token, Policy.DeviceAttribute attrib);

Description

This function returns a list of all possible values for the given attribute in DeviceFilter.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
attrib	Policy.DeviceAttribute, mandatory	—	The attribute name can be one of the following: •Policy.DeviceAttribute.MODEL •Policy.DeviceAttribute.GROUP

Return

This function returns an array of string representing all possible values for the attribute.

Error and Exception

When an error occurs, this function returns null.

enumerateSKUFilterAttribute

Synopsis

String[] enumerateSKUFilterAttribute(UserToken token, Policy.SKUAttribute attrib);

Description

This function returns a list of all possible values for the given attribute in SKUFilter.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
attrib	Policy.SKUAttribute, mandatory	—	The attribute name can be Policy.SKUAttribute.FEATURE_NAME.

Return

This function returns an array of string representing all possible values for the attribute.

Error and Exception

When an error occurs, this function returns null.

listAllPolicies

Synopsis

String[] listAllPolicies(UserToken token);

Description

This function returns a list of all policies that can be accessed by the user, including both the private policies owned by this user and all public policies.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.

Return

This function returns an array of string representing the IDs of the policies.

Error and Exception

When an error occurs, this function returns null.

listFilteredDevices

Synopsis

String[] listFilteredDevices(UserToken token, DeviceFilter dev_filter);

Description

This function generates a list of devices obtained by running the given device filter.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
dev_filter	DeviceFilter, mandatory	—	The input DeviceFilter object specifies the criteria for searching the list of devices.

Return

This function returns an array of string representing the IDs of the devices.

Error and Exception

When an error occurs, this function returns null.

listFilteredSKUs

Synopsis

SKUIdentifier[] listFilteredSKUs(UserToken token, SKUFilter sku_filter);

Description

This function returns a list of SKU identifiers resulting from running the SKU filter in the policy. The SKUIdentifier class used in this function is defined as follows:

class SKUIdentifier {

    String pak;                // PAK of the selected SKU

    String sku_name;           // name the selected SKU

}

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
sku_filter	SKUFilter, mandatory	—	The input SKUFilter object specifies the criteria for searching the list of devices.

Return

This function returns an array of SKUIdentifier objects.

Error and Exception

When an error occurs, this function returns null.

readPolicy

Synopsis

PolicyStatus readPolicy(UserToken token, String policy_name);

Description

This function retrieves a Policy object from data storage using the given name.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
policy_name	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	Name of the Policy object.

Return

This function returns a PolicyStatus object. The status and the policy object are contained in PolicyStatus.

Error and Exception

When an error occurs, the error code is contained in the PolicyStatus object.

writePolicy

Synopsis

Status writePolicy(UserToken token, Policy policy);

Description

This function writes the given Policy objects into data storage. The input Policy objects can be new instances of Policy returned by the createPolicy() function or existing ones retrieved from the data storage by the readPolicy() function.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
policy	Policy, mandatory	—	Policy objects, which can be new instances of Policy class or existing ones retrieved from the inventory by the readPolicy() function.

Return

This function returns Status objects.

Error and Exception

When an error occurs, the information is contained in the returned status object.