Extract Declarations

An extract declaration file allows you to define what sobjects and fields to extract from an org. An extract declaration can be specified directly as an option to the capture_sample_data task, but most often you will just edit the one attached to the sample dataset you are working on, such as datasets/default/default.extract.yml or datasets/qa/qa.extract.yml. This file is automatically generated by capture_sample_data or by Metecho.

An extract declaration looks like this:

extract:
    Opportunity:
        fields:
            - Name
            - ContactId
            - AccountId

This extracts opportunities explicitly, but also Accounts and Contacts implicitly, because ContactId and AccountId rely on them. In addition to the named fields, it extracts required fields of Opportunity, Contact and Account.

That declaration is therefore the same as:

# This will download the Salesforce-y trinity
# of Accounts, Contacts and Opportunities
extract:
    Opportunity:
        fields:
            - Name
            - ContactId
            - AccountId
            - FIELDS(REQUIRED)
    Account:
        fields:
            - FIELDS(REQUIRED)
    Contact:
        fields:
            - FIELDS(REQUIRED)

The FIELDS declarations can be REQUIRED, STANDARD, CUSTOM or ALL. In any case, you will alway get required fields.

So for example, you can extract all standard fields of Opportunity, all custom fields (plus required fields) of Account and all (createable) fields of Contact in general.

extract:
    Opportunity:
        fields:
            - FIELDS(STANDARD)
    Account:
        fields:
            - FIELDS(CUSTOM)
    Contact:
        fields:
            - FIELDS(ALL)

As a side effect, this will pull down many other objects referenced by fields that were referred to. For example … XXX

If you wanted to pull out many objects from an org, it might be easier to pull them out with with wildcards. There are wildcards for “all objects” (OBJECTS(ALL)), “all standard objects” (OBJECTS(STANDARD)), and “all custom objects” (OBJECTS(CUSTOM)). For example, to pull out all Account fields, all Standard Fields on Custom objects and all Custom fields on Standard objects (plus required fields) you would do this:

extract:
    Account:
        fields:
            - FIELDS(ALL)
    OBJECTS(CUSTOM):
        fields:
            - FIELDS(STANDARD)
    OBJECTS(ALL):
        fields:
            - FIELDS(CUSTOM)

If you want just a subset of records from an sobject, you can use a where clause.

extract:
    Account:
        fields:
            - FIELDS(ALL)
        where: FirstName='Buster'

<<<<<<< Updated upstream

Be careful with this feature: If this object has a child object that depends on it (e.g. Contact through AccountId) then child records may not link properly to their parent records.

Stashed changes If a particular sobject needs to explicitly be extracted with either the bulk or rest APIs, you can control that as well:

extract:
    Account:
        fields:
            - FIELDS(ALL)
        api: REST