Retrieve()

Retrieve an array of folders that meet the criteria that you specify.

Syntax

Retrieve(1)

Function Properties

JSON Object Structure for a Basic Search

A simple search contains a single criterion. To perform a simple search, pass a JSON object that contains a Property, a SimpleOperator, and a Value. In some cases, such as when you search for a null value, you can omit the Value.

For example, a simple search can return all folders with an ID between 123456 and 234567, as shown in this code sample.

{
  Property: "ID",
  SimpleOperator: "between",
  Value: ["123456","234567"]
}

JSON Object Structure for a Complex Search

A complex search contains two criteria that are connected with AND or OR logic. To perform a complex search, pass a JSON object that contains a LeftOperand object, a LogicalOperator, and a RightOperand object.

Both the LeftOperand and RightOperand objects contain the same content as a simple query. That is, they both contain a Property, a SimpleOperator, and a Value.

The value of LogicalOperator is either AND or OR, depending on the type of logic that you want to use to connect the two operands.

This sample shows a complex search that returns image folders where the name of the folder contains the phrase "LoyaltyRewards."

{
  LeftOperand: {
    Property: "ContentType",
    SimpleOperator: "equals",
    Value: "image"
  },
  LogicalOperator: "AND",
  RightOperand: {
    Property: "Name",
    SimpleOperator: "like",
    Value: "LoyaltyRewards%"
  }
}

Property

The Property contains the name of the field to perform the search in. For example, to search for folders based on their name, specify Name. This table lists several common properties.

You can also use dot notation to specify fields in child objects. For example, to search based on the name of the parent folder, specify ParentFolder.Name.

SimpleOperator

For the SimpleOperator property, specify the comparison that you want to perform between the Property and the Value. This table lists the comparisons that you can perform.

Value

For the Value property, specify the value that you want to search for.

If you specify contentType for the Property value, specify the type of folder you want to return. This table lists the possible values for this property.

Usage

To use this function, pass a JSON object that defines your search criteria. The structure of the JSON object differs based on whether you want to perform a simple search or a complex one.

Simple Search Example

In a simple search, the JSON object contains the Property, SimpleOperator, and Value properties. This example returns a list of folders that belong to a parent folder named RewardsProgram.

<script runat="server">
  Platform.Load("core", "1");

  var folders = Folder.Retrieve({
    Property: "ParentFolder.Name",
    SimpleOperator: "equals",
    Value: "RewardsProgram"
  });

  Write(Stringify(folders));
</script>

Complex Search Example

In a complex search, the JSON object contains LeftOperand and RightOperand objects and a LogicalOperator property. The LeftOperand and RightOperand objects each contain a set of Property, SimpleOperator, and Value properties.

This example returns a list of folders in the My Images folder with names that begin with the text "LoyaltyRewards" followed by zero or more other characters.

<script runat="server">
  Platform.Load("core", "1");

  var folders = Folder.Retrieve({
    LeftOperand: {
      Property: "ContentType",
      SimpleOperator: "equals",
      Value: "image"
    },
    LogicalOperator: "AND",
    RightOperand: {
      Property: "Name",
      SimpleOperator: "like",
      Value: "LoyaltyRewards%"
    }
  });

  Write(Stringify(folders));
</script>

Result

Whether you perform a simple or complex search, the structure of the result is the same. The result is a JSON array that contains folder objects. Each folder object also contains an object that describes the properties of the parent folder.

[
  {
    "Name": "LoyaltyRewardsProgramme",
    "ID": 445566,
    "IDSpecified": true,
    "ParentFolder": {
      "Name": "my images",
      "ID": 112233,
      "IDSpecified": true,
      "ParentFolder": null,
      "Description": "",
      "ContentType": "image",
      "IsActive": true,
      "IsActiveSpecified": true,
      "IsEditable": false,
      "IsEditableSpecified": true,
      "AllowChildren": true,
      "AllowChildrenSpecified": true,
      "Client": null,
      "PartnerKey": null,
      "PartnerProperties": null,
      "CreatedDate": "0001-01-01T00:00:00.000",
      "CreatedDateSpecified": false,
      "ModifiedDate": null,
      "ModifiedDateSpecified": false,
      "ObjectID": "af7ca448-b9a2-4a19-83fa-0290cdddd91d",
      "CustomerKey": null,
      "Owner": null,
      "CorrelationID": null,
      "ObjectState": null,
      "IsPlatformObject": false,
      "IsPlatformObjectSpecified": false
    },
    "Description": "",
    "ContentType": "image",
    "IsActive": true,
    "IsActiveSpecified": true,
    "IsEditable": false,
    "IsEditableSpecified": true,
    "AllowChildren": false,
    "AllowChildrenSpecified": true,
    "Client": null,
    "PartnerKey": null,
    "PartnerProperties": null,
    "CreatedDate": "0001-01-01T00:00:00.000",
    "CreatedDateSpecified": false,
    "ModifiedDate": null,
    "ModifiedDateSpecified": false,
    "ObjectID": null,
    "CustomerKey": "",
    "Owner": null,
    "CorrelationID": null,
    "ObjectState": null,
    "IsPlatformObject": false,
    "IsPlatformObjectSpecified": false
  },
  ...
]