ORKResult Class Reference

Inherits from NSObject
Conforms to NSCopying
NSSecureCoding
Declared in ORKResult.h

The ORKResult class defines the attributes of a result from one step or a group of steps. When you use the ResearchKit framework APIs, you typically get a result from the result property of either ORKTaskViewController or ORKStepViewController. Certain types of results can contain other results, which together express a hierarchy; examples of these types of results are ORKCollectionResult subclasses, such as ORKStepResult and ORKTaskResult.

When you receive a result, you can store it temporarily by archiving it with NSKeyedArchiver, because all ORKResult objects implement NSSecureCoding. If you want to serialize the result object to other formats, you’re responsible for implementing this.

The result object hierarchy does not necessarily include all the data collected during a task. Some result objects, such as ORKFileResult, may refer to files in the filesystem that were generated during the task. These files are easy to find, because they are all located in the output directory of the task view controller.

It’s recommended that you use NSFileProtectionComplete (at a minimum) to protect these files, and that you similarly protect all serialization of ORKResult objects that you write to disk. It is also generally helpful to keep the results together with the referenced files as you submit them to a back-end server. For example, it can be convenient to zip all data corresponding to a particular task result into a single compressed archive.

Every object in the result hierarchy has an identifier that should correspond to the identifier of an object in the original step hierarchy. Similarly, every object has a start date and an end date that correspond to the range of times during which the result was collected. In an ORKStepResult object, for example, the start and end dates cover the range of time during which the step view controller was visible on screen.

When you implement a new type of step, it is usually helpful to create a new ORKResult subclass to hold the type of result data the step can generate, unless it makes sense to use an existing subclass. Return your custom result subclass as one of the results attached to the step’s ORKStepResult object.

Other Methods

– initWithIdentifier:

Returns an initialized result using the specified identifier.

- (instancetype)initWithIdentifier:(NSString *)identifier

Parameters

identifier

The unique identifier of the result.

Discussion

Typically, objects such as ORKStepViewController and ORKTaskViewController instantiate result (and ORKResult subclass) objects; you seldom need to instantiate a result object in your code.

Declared In

ORKResult.h

  identifier

A meaningful identifier for the result.

@property (nonatomic, copy) NSString *identifier

Discussion

The identifier can be used to identify the question that was asked or the task that was completed to produce the result. Typically, the identifier is copied from the originating object by the view controller or recorder that produces it.

For example, a task result receives its identifier from a task, a step result receives its identifier from a step, and a question result receives its identifier from a step or a form item. Results that are generated by recorders also receive an identifier that corresponds to that recorder.

Declared In

ORKResult.h

  startDate

The time when the task, step, or data collection began.

@property (nonatomic, copy) NSDate *startDate

Discussion

The value of this property is set by the view controller or recorder that produces the result, to indicate when data collection started.

Note that for instantaneous items, startDate and endDate can have the same value, and should generally correspond to the end of the instantaneous data collection period.

Declared In

ORKResult.h

  endDate

The time when the task, step, or data collection stopped.

@property (nonatomic, copy) NSDate *endDate

Discussion

The value of this property is set by the view controller or recorder that produces the result, to indicate when data collection stopped.

Note that for instantaneous items, startDate and endDate can have the same value, and should generally correspond to the end of the instantaneous data collection period.

Declared In

ORKResult.h

  userInfo

Metadata that describes the conditions under which the result was acquired.

@property (nonatomic, copy, nullable) NSDictionary *userInfo

Discussion

The userInfo dictionary can be set by the view controller or recorder that produces the result. However, it’s often a better choice to use a new ORKResult subclass for passing additional information back to code that uses the framework, because using typed accessors is safer than using a dictionary.

The user info dictionary must contain only keys and values that are suitable for property list or JSON serialization.

Declared In

ORKResult.h

Extension Methods

  saveable

A boolean value indicating whether this result can be saved in a save and restore procedure.

@property (nonatomic, readonly, getter=isSaveable) BOOL saveable

Discussion

This is currently considered a private method, but overriding the getter in a result is the correct way to prevent this result being considered as saveable for the purpose of deciding whether to offer a “Save” option when the user cancels a task in progress.

ORKResult subclasses should return YES if they have data that the user might want to be able to restore if the task were interrupted and later resumed from the current state.

Declared In

ORKResult_Private.h