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
orrest
APIs, you can control that as well:
extract:
Account:
fields:
- FIELDS(ALL)
api: REST