PcoGivingBatch class
This class represents a PCO Giving Batch Object
- Application: giving
- Id: batch
- Type: Batch
- ApiVersion: 2019-10-18
- Is Deprecated: false
- Is Collection Only: false
- Default Endpoint: https://api.planningcenteronline.com/giving/v2/batches
- Create Endpoint: https://api.planningcenteronline.com/giving/v2/batches
Instantiation
- Create a new instance using the
PcoGivingBatch()
constructor - Instantiate from existing
JSON
data using thePcoGivingBatch.fromJson()
constructor. - Load an instance from the API using one of the static methods defined on this class.
Usage
- Fields exposed by the API are readable through getter methods.
- Fields writable by the API are exposed through setter methods.
- Original
json
data is exposed through the read-onlyattributes
map. - Additional data is available through the read-only
links
andrelationships
maps. - Available relationships / includes are exposed through typed getters.
Description
A Batch
is a collection of Donation
s. When creating Donation
's via the API, you're required to put them in a Batch
.
When a Batch
is first created, it's in the in_progress
or "uncommitted" state. You can freely add/remove/modify Donation
s in this Batch
and they won't show up in a donor's donation history online, they won't appear in any donor statements issued by the Giving admin, and changes to these donations are not flagged in the system log. Think of it as a staging area for donations.
When a Batch
is committed (see more in the Actions section), all of the Donation
s within it are also marked as "committed". At that point, they're visible to donors in their online history, and any further edits made to those Donation
s are logged and visible to Giving admins.
With all of that in mind, you can use Batch
es in one of two ways:
- Create an uncommitted
Batch
, addDonation
s to it, then commit theBatch
. - Create a
Batch
, commit it, then addDonation
s to it.
In both cases, the end result is the same. The main difference is that option #2 does not provide you/other admins the opportunity to fix any mistakes before changes are logged and Donation
s are made visible to donors. Any Donation
s added to a committed Batch
will automatically be committed as well.
Whichever route you decide to take, it's helpful to make use of the Batch
's description to help differentiate these groupings from each other and from other Batch
es that the Giving admins might be creating on their own.
Attributes (and permissions)
id
(ro) -> PCO:id
createdAt
(ro) -> PCO:created_at
updatedAt
(ro) -> PCO:updated_at
committedAt
(ro) -> PCO:committed_at
description
(rw) -> PCO:description
donationsCount
(ro) -> PCO:donations_count
totalCents
(ro) -> PCO:total_cents
totalCurrency
(ro) -> PCO:total_currency
status
(ro) -> PCO:status
Edges and Actions
Outbound Edges:
batchgroup-batch-batch_group
: https://api.planningcenteronline.com/giving/v2/batches/1/batch_groupdonation-batch-donations
: https://api.planningcenteronline.com/giving/v2/batches/1/donationsperson-batch-owner
: https://api.planningcenteronline.com/giving/v2/batches/1/owner
Inbound Edges:
batch-batchgroup-batches
: https://api.planningcenteronline.com/giving/v2/batch_groups/1/batchesbatch-organization-batches
: https://api.planningcenteronline.com/giving/v2/batchesbatch-person-batches
: https://api.planningcenteronline.com/giving/v2/people/1/batches
Actions:
Raw Data Object Example
{
"type": "Batch",
"id": "1",
"attributes": {
"created_at": "2000-01-01T12:00:00Z",
"updated_at": "2000-01-01T12:00:00Z",
"committed_at": "2000-01-01T12:00:00Z",
"description": "string",
"total_cents": 1,
"total_currency": "string",
"status": "string"
},
"relationships": {
"batch_group": {
"data": {
"type": "BatchGroup",
"id": "1"
}
}
}
}
- Inheritance
-
- Object
- PcoResource
- PcoGivingBatch
Constructors
-
PcoGivingBatch({String? id, DateTime? createdAt, DateTime? updatedAt, DateTime? committedAt, String? description, int? donationsCount, int? totalCents, String? totalCurrency, String? status, Map<
String, List< ? withRelationships, List<PcoResource> >PcoResource> ? withIncluded}) -
Create a new PcoGivingBatch object using this endpoint:
https://api.planningcenteronline.com/giving/v2/batches
factory - PcoGivingBatch.empty()
- Create an empty instance of this class. This is only useful when an endpoint requires related or included data.
-
PcoGivingBatch.fromJson(Map<
String, dynamic> data, {List<Map< ? withIncluded})String, dynamic> >
Properties
- api → PlanningCenter
-
planning center resources must be tied to an api
no setterinherited
- apiEndpoint → String
-
no setterinherited
- apiPath → String
-
PcoResources include their own path as a link object
but this might be null if we haven't created/fetched the object yet
Child classes should redefine this getter to allow for manual path overrides
no setteroverride
- apiVersion → String
-
child classes can override these getters which will allow
methods in this class to see static variables from child classes
no setteroverride
-
attributes
→ ReadOnlyMapView<
String, dynamic> -
contains the underlying attributes returned by the api
and allows a user to access arbitrary data in the attributes by actual api name
no setterinherited
- canCreate → bool
-
no setteroverride
- canDestroy → bool
-
no setteroverride
- canUpdate → bool
-
no setteroverride
- committedAt → DateTime
-
no setter
-
createAllowed
→ List<
String> -
no setteroverride
- createdAt → DateTime
-
no setterinherited
- createPathTemplate → String
-
no setteroverride
- defaultPathTemplate → String
-
no setteroverride
- description ↔ String
-
A brief description of what a batch is for. This is displayed in Giving to help differentiate different batches from one another. If no description is provided for a batch, it will be referred to as
Untitled batch
within Giving.getter/setter pair - donationsCount → int
-
no setter
- fetched ↔ bool
-
indicate whether an item is full or partial
getter/setter pairinherited
- hashCode → int
-
The hash code for this object.
no setterinherited
- id → String?
-
no setterinherited
-
included
→ List<
PcoResource> -
contains included items parsed into objects
no setterinherited
- includedBatchGroup → PcoGivingBatchGroup?
-
no setter
-
links
→ ReadOnlyMapView<
String, dynamic> -
contains the links data returned by the api if present
no setterinherited
- needsSave → bool
-
no setterinherited
- pcoApplication ↔ String
-
latefinalinherited
-
relationships
→ ReadOnlyMapView<
String, List< PcoResource> > -
contains relationships parsed into objects
even though the api sends relationship objects as Maps or Lists
we always put them into lists for consistency
no setterinherited
- resourceType ↔ String
-
all planning center resources must have a
type
latefinalinherited - runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- slug → String
-
no setterinherited
- status → String
-
no setter
- totalCents → int
-
no setter
- totalCurrency → String
-
no setter
-
updateAllowed
→ List<
String> -
no setteroverride
- updatedAt → DateTime
-
no setterinherited
Methods
-
coerceDouble(
dynamic a) → double -
inherited
-
coerceInt(
dynamic a) → int -
inherited
-
commit(
Object data) → Future< PlanningCenterApiResponse< PlanningCenterApiData> > -
ACTION:
commit
-
delete(
) → Future< PlanningCenterApiResponse< PlanningCenterApiData> > -
inherited
-
filteredAttributes(
List< String> allowedKeys) → Map<String, dynamic> -
inherited
-
fromJson(
Map< String, dynamic> data, {List<Map< ? withIncluded}) → dynamicString, dynamic> > -
Takes a full JSON:API Response Object (the contents of a "data" field)
will clear and update id, apiPath, attributes and
_relationships
inherited -
getBatchGroup(
{PcoGivingBatchGroupQuery? query}) → Future< PcoCollection< PcoGivingBatchGroup> > -
Will get a collection of PcoGivingBatchGroup objects (expecting one)
using a path like this:
https://api.planningcenteronline.com/giving/v2/batches/1/batch_group
-
getDonations(
{PcoGivingDonationQuery? query}) → Future< PcoCollection< PcoGivingDonation> > -
Will get a collection of PcoGivingDonation objects (expecting many)
using a path like this:
https://api.planningcenteronline.com/giving/v2/batches/1/donations
-
getOwner(
{PcoGivingPersonQuery? query}) → Future< PcoCollection< PcoGivingPerson> > -
Will get a collection of PcoGivingPerson objects (expecting many)
using a path like this:
https://api.planningcenteronline.com/giving/v2/batches/1/owner
-
handleIncludes(
List< Map< included) → voidString, dynamic> > -
This function populates the relationships with typed resource objects
based on the data in the
included
map of the json.inherited -
handleItem(
Map< String, dynamic> data) → PcoResource? -
inherited
-
handleRelationships(
Map< String, dynamic> items, [List<Map< included = const []]) → Map<String, dynamic> >String, List< PcoResource> > -
inherited
-
includedOwner<
T extends PcoResource> () → List< T> - The code generator could not automatically determine the resource type of this relationship. For type safe code, you should specify it in the type argument when calling.
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
save(
{Map< String, PcoResource> ? withRelated, List<PcoResource> ? withIncluded}) → Future<PlanningCenterApiResponse< PlanningCenterApiData> > -
Many Planning Center endpoints allow or require additional relationships and/or included items
to be sent with a create/update operation. Since these cannot always be determined by the automatic
code generation, they may be included as arguments to the save operation.
inherited
-
toCreateResource(
) → Map< String, dynamic> -
create the attributes Map for this object without the
id
field using only the attributes allowed in create (post) operationsinherited -
toDataMap(
{Map< String, PcoResource> ? withRelated, List<PcoResource> ? withIncluded}) → Map<String, dynamic> -
create a json-api Map for this object automatically selecting create or update
based on the existence of the
id
field. Will result in something like this:inherited -
toIdResource(
) → Map< String, dynamic> -
returns the simplest representation of this resource with
only the type and the id:
inherited
-
toJson(
{dynamic includeAttributes = true, dynamic includeRelationships = false}) → Map< String, dynamic> -
Some api requests only want the type and id of an object.
In those cases, set
includeAttributes
to false or call toIdResource instead.inherited -
toString(
) → String -
A string representation of this object.
inherited
-
toUpdateResource(
) → Map< String, dynamic> -
create the attributes Map for this object using only
the attributes allowed in update (patch) operations
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Properties
-
canInclude
→ List<
String> -
possible includes with parameter ?include=a,b
no setter
-
canOrderBy
→ List<
String> -
possible orderings with parameter ?order=
no setter
-
canQuery
→ List<
String> -
possible queries using parameters like ?where
key
=value or ?wheregt|lt
=valueno setter
Static Methods
-
get(
{String? id, PcoGivingBatchQuery? query, bool getAll = false, bool includeAllRelated = false, bool includeBatchGroup = false, bool includeOwner = false}) → Future< PcoCollection< PcoGivingBatch> > -
Will get a
PcoCollection
of PcoGivingBatch objects (expecting many) using a path like this:/giving/v2/batches
-
getAll(
{String? id, PcoGivingBatchQuery? query, bool includeAllRelated = false, bool includeBatchGroup = false, bool includeOwner = false}) → Future< PcoCollection< PcoGivingBatch> > -
Will get a
PcoCollection
containing ALL PcoGivingBatch objects (expecting many) using a path like this:/giving/v2/batches
-
getAllFromBatchGroup(
String batchGroupId, {String? id, PcoGivingBatchQuery? query, bool includeAllRelated = false, bool includeBatchGroup = false, bool includeOwner = false}) → Future< PcoCollection< PcoGivingBatch> > -
Will get a
PcoCollection
containing ALL PcoGivingBatch objects (expecting many) using a path like this:/giving/v2/batch_groups/$batchGroupId/batches
-
getAllFromPerson(
String personId, {String? id, PcoGivingBatchQuery? query, bool includeAllRelated = false, bool includeBatchGroup = false, bool includeOwner = false}) → Future< PcoCollection< PcoGivingBatch> > -
Will get a
PcoCollection
containing ALL PcoGivingBatch objects (expecting many) using a path like this:/giving/v2/people/$personId/batches
-
getFromBatchGroup(
String batchGroupId, {String? id, PcoGivingBatchQuery? query, bool getAll = false, bool includeAllRelated = false, bool includeBatchGroup = false, bool includeOwner = false}) → Future< PcoCollection< PcoGivingBatch> > -
Will get a
PcoCollection
of PcoGivingBatch objects (expecting many) using a path like this:/giving/v2/batch_groups/$batchGroupId/batches
-
getFromPerson(
String personId, {String? id, PcoGivingBatchQuery? query, bool getAll = false, bool includeAllRelated = false, bool includeBatchGroup = false, bool includeOwner = false}) → Future< PcoCollection< PcoGivingBatch> > -
Will get a
PcoCollection
of PcoGivingBatch objects (expecting many) using a path like this:/giving/v2/people/$personId/batches
-
getSingle(
String id, {PcoGivingBatchQuery? query, bool includeAllRelated = false, bool includeBatchGroup = false, bool includeOwner = false}) → Future< PcoGivingBatch?> -
Will get a single
PcoGivingBatch
object using a path like this:/giving/v2/batches/[id]
-
getSingleFromBatchGroup(
String batchGroupId, String id, {PcoGivingBatchQuery? query, bool includeAllRelated = false, bool includeBatchGroup = false, bool includeOwner = false}) → Future< PcoGivingBatch?> -
Will get a single
PcoGivingBatch
object using a path like this:/giving/v2/batch_groups/$batchGroupId/batches/[id]
-
getSingleFromPerson(
String personId, String id, {PcoGivingBatchQuery? query, bool includeAllRelated = false, bool includeBatchGroup = false, bool includeOwner = false}) → Future< PcoGivingBatch?> -
Will get a single
PcoGivingBatch
object using a path like this:/giving/v2/people/$personId/batches/[id]
Constants
- kApiVersion → const String
- kCommittedAt → const String
- kCreatedAt → const String
- kCreatePathTemplate → const String
- kDefaultPathTemplate → const String
- kDescription → const String
- kDonationsCount → const String
- kId → const String
- kPcoApplication → const String
- kStatus → const String
- kTotalCents → const String
- kTotalCurrency → const String
- kTypeId → const String
- kTypeString → const String
- kUpdatedAt → const String